BIRD Programmer's Documentation <author> Ondrej Filip <it/<feela@network.cz>/, Pavel Machek <it/<pavel@ucw.cz>/, Martin Mares <it/<mj@ucw.cz>/, Ondrej Zajicek <it/<santiago@crfreenet.org>/ </author> <abstract> This document contains programmer's documentation for the BIRD Internet Routing Daemon project. </abstract>  <toc>  <chapt>BIRD Design <sect>Introduction This document describes the internal workings of BIRD, its architecture, design decisions and rationale behind them. It also contains documentation on all the essential components of the system and their interfaces. Routing daemons are complicated things which need to act in real time to complex sequences of external events, respond correctly even to the most erroneous behavior of their environment and still handle enormous amount of data with reasonable speed. Due to all of this, their design is very tricky as one needs to carefully balance between efficiency, stability and (last, but not least) simplicity of the program and it would be possible to write literally hundreds of pages about all of these issues. In accordance to the famous quote of Anton Chekhov "Shortness is a sister of talent", we've tried to write a much shorter document highlighting the most important stuff and leaving the boring technical details better explained by the program source itself together with comments contained therein. <sect>Design goals When planning the architecture of BIRD, we've taken a close look at the other existing routing daemons and also at some of the operating systems used on dedicated routers, gathered all important features and added lots of new ones to overcome their shortcomings and to better match the requirements of routing in today's Internet: IPv6, policy routing, route filtering and so on. From this planning, the following set of design goals has arisen: <itemize> <item><it>Support all the standard routing protocols and make it easy to add new ones.</it> This leads to modularity and clean separation between the core and the protocols. <item><it>Support both IPv4 and IPv6 in the same source tree, re-using most of the code.</it> This leads to abstraction of IP addresses and operations on them. <item><it>Minimize OS dependent code to make porting as easy as possible.</it> Unfortunately, such code cannot be avoided at all as the details of communication with the IP stack differ from OS to OS and they often vary even between different versions of the same OS. But we can isolate such code in special modules and do the porting by changing or replacing just these modules. Also, don't rely on specific features of various operating systems, but be able to make use of them if they are available. <item><it>Allow multiple routing tables.</it> Easily solvable by abstracting out routing tables and the corresponding operations. <item><it>Offer powerful route filtering.</it> There already were several attempts to incorporate route filters to a dynamic router, but most of them have used simple sequences of filtering rules which were very inflexible and hard to use for non-trivial filters. We've decided to employ a simple loop-free programming language having access to all the route attributes and being able to modify the most of them. <item><it>Support easy configuration and re-configuration.</it> Most routers use a simple configuration language designed ad hoc with no structure at all and allow online changes of configuration by using their command-line interface, thus any complex re-configurations are hard to achieve without replacing the configuration file and restarting the whole router. We've decided to use a more general approach: to have a configuration defined in a context-free language with blocks and nesting, to perform all configuration changes by editing the configuration file, but to be able to read the new configuration and smoothly adapt to it without disturbing parts of the routing process which are not affected by the change. <item><it>Be able to be controlled online.</it> In addition to the online reconfiguration, a routing daemon should be able to communicate with the user and with many other programs (primarily scripts used for network maintenance) in order to make it possible to inspect contents of routing tables, status of all routing protocols and also to control their behavior (disable, enable or reset a protocol without restarting all the others). To achieve this, we implement a simple command-line protocol based on those used by FTP and SMTP (that is textual commands and textual replies accompanied by a numeric code which makes them both readable to a human and easy to recognize in software). <item><it>Respond to all events in real time.</it> A typical solution to this problem is to use lots of threads to separate the workings of all the routing protocols and also of the user interface parts and to hope that the scheduler will assign time to them in a fair enough manner. This is surely a good solution, but we have resisted the temptation and preferred to avoid the overhead of threading and the large number of locks involved and preferred a event driven architecture with our own scheduling of events. An unpleasant consequence of such an approach is that long lasting tasks must be split to more parts linked by special events or timers to make the CPU available for other tasks as well. </itemize> <sect>Architecture The requirements set above have lead to a simple modular architecture containing the following types of modules: <descrip> <tagp>Core modules</tagp> implement the core functions of BIRD: taking care of routing tables, keeping protocol status, interacting with the user using the Command-Line Interface (to be called CLI in the rest of this document) etc. <tagp>Library modules</tagp> form a large set of various library functions implementing several data abstractions, utility functions and also functions which are a part of the standard libraries on some systems, but missing on other ones. <tagp>Resource management modules</tagp> take care of resources, their allocation and automatic freeing when the module having requested shuts itself down. <tagp>Configuration modules</tagp> are fragments of lexical analyzer, grammar rules and the corresponding snippets of C code. For each group of code modules (core, each protocol, filters) there exist a configuration module taking care of all the related configuration stuff. <tagp>The filter</tagp> implements the route filtering language. <tagp>Protocol modules</tagp> implement the individual routing protocols. <tagp>System-dependent modules</tagp> implement the interface between BIRD and specific operating systems. <tagp>The client</tagp> is a simple program providing an easy, though friendly interface to the CLI. </descrip> <sect>Implementation BIRD has been written in GNU C. We've considered using C++, but we've preferred the simplicity and straightforward nature of C which gives us fine control over all implementation details and on the other hand enough instruments to build the abstractions we need. The modules are statically linked to produce a single executable file (except for the client which stands on its own). The building process is controlled by a set of Makefiles for GNU Make, intermixed with several Perl and shell scripts. The initial configuration of the daemon, detection of system features and selection of the right modules to include for the particular OS and the set of protocols the user has chosen is performed by a configure script generated by GNU Autoconf. The parser of the configuration is generated by the GNU Bison. The documentation is generated using <file/SGMLtools/ with our own DTD and mapping rules which produce both an online version in HTML and a neatly formatted one for printing (first converted from SGML to &latex; and then processed by &tex; and <file/dvips/ to get a PostScript file). The comments from C sources which form a part of the programmer's documentation are extracted using a modified version of the <file/kernel-doc/ tool. If you want to work on BIRD, it's highly recommended to configure it with a <tt/--enable-debug/ switch which enables some internal consistency checks and it also links BIRD with a memory allocation checking library if you have one (either <tt/efence/ or <tt/dmalloc/).  <chapt>Core <sect>Forwarding Information Base FIB is a data structure designed for storage of routes indexed by their network prefixes. It supports insertion, deletion, searching by prefix, `routing' (in CIDR sense, that is searching for a longest prefix matching a given IP address) and (which makes the structure very tricky to implement) asynchronous reading, that is enumerating the contents of a FIB while other modules add, modify or remove entries. Internally, each FIB is represented as a collection of nodes of type <struct/fib_node/ indexed using a sophisticated hashing mechanism. We use two-stage hashing where we calculate a 16-bit primary hash key independent on hash table size and then we just divide the primary keys modulo table size to get a real hash key used for determining the bucket containing the node. The lists of nodes in each bucket are sorted according to the primary hash key, hence if we keep the total number of buckets to be a power of two, re-hashing of the structure keeps the relative order of the nodes. To get the asynchronous reading consistent over node deletions, we need to keep a list of readers for each node. When a node gets deleted, its readers are automatically moved to the next node in the table. Basic FIB operations are performed by functions defined by this module, enumerating of FIB contents is accomplished by using the <func/FIB_WALK()/ macro or <func/FIB_ITERATE_START()/ if you want to do it asynchronously. For simple iteration just place the body of the loop between <func/FIB_WALK()/ and <func/FIB_WALK_END()/. You can't modify the FIB during the iteration (you can modify data in the node, but not add or remove nodes). If you need more freedom, you can use the FIB_ITERATE_*() group of macros. First, you initialize an iterator with <func/FIB_ITERATE_INIT()/. Then you can put the loop body in between <func/FIB_ITERATE_START()/ and <func/FIB_ITERATE_END()/. In addition, the iteration can be suspended by calling <func/FIB_ITERATE_PUT()/. This'll link the iterator inside the FIB. While suspended, you may modify the FIB, exit the current function, etc. To resume the iteration, enter the loop again. You can use <func/FIB_ITERATE_UNLINK()/ to unlink the iterator (while iteration is suspended) in cases like premature end of FIB iteration. Note that the iterator must not be destroyed when the iteration is suspended, the FIB would then contain a pointer to invalid memory. Therefore, after each <func/FIB_ITERATE_INIT()/ or <func/FIB_ITERATE_PUT()/ there must be either <func/FIB_ITERATE_START()/ or <func/FIB_ITERATE_UNLINK()/ before the iterator is destroyed. <function><type>void</type> <funcdef>fib_init</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct fib *</type> <param>f</param></tagp> the FIB to be initialized (the structure itself being allocated by the caller) <tagp><type>pool *</type> <param>p</param></tagp> pool to allocate the nodes in <tagp><type>unsigned</type> <param>node_size</param></tagp> node size to be used (each node consists of a standard header <struct/fib_node/ followed by user data) <tagp><type>unsigned</type> <param>hash_order</param></tagp> initial hash order (a binary logarithm of hash table size), 0 to use default order (recommended) <tagp><type>fib_init_func</type> <param>init</param></tagp> pointer a function to be called to initialize a newly created node </descrip> <funcsect>Description This function initializes a newly allocated FIB and prepares it for use. </function> <function><type>void *</type> <funcdef>fib_find</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct fib *</type> <param>f</param></tagp> FIB to search in <tagp><type>ip_addr *</type> <param>a</param></tagp> pointer to IP address of the prefix <tagp><type>int</type> <param>len</param></tagp> prefix length </descrip> <funcsect>Description Search for a FIB node corresponding to the given prefix, return a pointer to it or <const/NULL/ if no such node exists. </function> <function><type>void *</type> <funcdef>fib_get</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct fib *</type> <param>f</param></tagp> FIB to work with <tagp><type>ip_addr *</type> <param>a</param></tagp> pointer to IP address of the prefix <tagp><type>int</type> <param>len</param></tagp> prefix length </descrip> <funcsect>Description Search for a FIB node corresponding to the given prefix and return a pointer to it. If no such node exists, create it. </function> <function><type>void *</type> <funcdef>fib_route</funcdef> (<type>struct fib *</type> <param>f</param>, <type>ip_addr</type> <param>a</param>, <type>int</type> <param>len</param>) -- CIDR routing lookup <funcsect>Arguments <descrip> <tagp><type>struct fib *</type> <param>f</param></tagp> FIB to search in <tagp><type>ip_addr</type> <param>a</param></tagp> pointer to IP address of the prefix <tagp><type>int</type> <param>len</param></tagp> prefix length </descrip> <funcsect>Description Search for a FIB node with longest prefix matching the given network, that is a node which a CIDR router would use for routing that network. </function> <function><type>void</type> <funcdef>fib_delete</funcdef> (<type>struct fib *</type> <param>f</param>, <type>void *</type> <param>E</param>) -- delete a FIB node <funcsect>Arguments <descrip> <tagp><type>struct fib *</type> <param>f</param></tagp> FIB to delete from <tagp><type>void *</type> <param>E</param></tagp> entry to delete </descrip> <funcsect>Description This function removes the given entry from the FIB, taking care of all the asynchronous readers by shifting them to the next node in the canonical reading order. </function> <function><type>void</type> <funcdef>fib_free</funcdef> (<type>struct fib *</type> <param>f</param>) -- delete a FIB <funcsect>Arguments <descrip> <tagp><type>struct fib *</type> <param>f</param></tagp> FIB to be deleted </descrip> <funcsect>Description This function deletes a FIB -- it frees all memory associated with it and all its entries. </function> <function><type>void</type> <funcdef>fib_check</funcdef> (<type>struct fib *</type> <param>f</param>) -- audit a FIB <funcsect>Arguments <descrip> <tagp><type>struct fib *</type> <param>f</param></tagp> FIB to be checked </descrip> <funcsect>Description This debugging function audits a FIB by checking its internal consistency. Use when you suspect somebody of corrupting innocent data structures. </function> <sect>Routing tables Routing tables are probably the most important structures BIRD uses. They hold all the information about known networks, the associated routes and their attributes. There are multiple routing tables (a primary one together with any number of secondary ones if requested by the configuration). Each table is basically a FIB containing entries describing the individual destination networks. For each network (represented by structure <struct/net/), there is a one-way linked list of route entries (<struct/rte/), the first entry on the list being the best one (i.e., the one we currently use for routing), the order of the other ones is undetermined. The <struct/rte/ contains information specific to the route (preference, protocol metrics, time of last modification etc.) and a pointer to a <struct/rta/ structure (see the route attribute module for a precise explanation) holding the remaining route attributes which are expected to be shared by multiple routes in order to conserve memory. <function><type>rte *</type> <funcdef>rte_find</funcdef> (<type>net *</type> <param>net</param>, <type>struct rte_src *</type> <param>src</param>) -- find a route <funcsect>Arguments <descrip> <tagp><type>net *</type> <param>net</param></tagp> network node <tagp><type>struct rte_src *</type> <param>src</param></tagp> route source </descrip> <funcsect>Description The <func/rte_find()/ function returns a route for destination <param/net/ which is from route source <param/src/. </function> <function><type>rte *</type> <funcdef>rte_get_temp</funcdef> (<type>rta *</type> <param>a</param>) -- get a temporary <struct/rte/ <funcsect>Arguments <descrip> <tagp><type>rta *</type> <param>a</param></tagp> attributes to assign to the new route (a <struct/rta/; in case it's un-cached, <func/rte_update()/ will create a cached copy automatically) </descrip> <funcsect>Description Create a temporary <struct/rte/ and bind it with the attributes <param/a/. Also set route preference to the default preference set for the protocol. </function> <function><type>rte *</type> <funcdef>rte_cow_rta</funcdef> (<type>rte *</type> <param>r</param>, <type>linpool *</type> <param>lp</param>) -- get a private writable copy of <struct/rte/ with writable <struct/rta/ <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>r</param></tagp> a route entry to be copied <tagp><type>linpool *</type> <param>lp</param></tagp> a linpool from which to allocate <struct/rta/ </descrip> <funcsect>Description <func/rte_cow_rta()/ takes a <struct/rte/ and prepares it and associated <struct/rta/ for modification. There are three possibilities: First, both <struct/rte/ and <struct/rta/ are private copies, in that case they are returned unchanged. Second, <struct/rte/ is private copy, but <struct/rta/ is cached, in that case <struct/rta/ is duplicated using <func/rta_do_cow()/. Third, both <struct/rte/ is shared and <struct/rta/ is cached, in that case both structures are duplicated by <func/rte_do_cow()/ and <func/rta_do_cow()/. Note that in the second case, cached <struct/rta/ loses one reference, while private copy created by <func/rta_do_cow()/ is a shallow copy sharing indirect data (eattrs, nexthops, ...) with it. To work properly, original shared <struct/rta/ should have another reference during the life of created private copy. <funcsect>Result a pointer to the new writable <struct/rte/ with writable <struct/rta/. </function> <function><type>void</type> <funcdef>rte_announce</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>tab</param></tagp> table the route has been added to <tagp><type>unsigned</type> <param>type</param></tagp> type of route announcement (RA_OPTIMAL or RA_ANY) <tagp><type>net *</type> <param>net</param></tagp> network in question <tagp><type>rte *</type> <param>new</param></tagp> the new route to be announced <tagp><type>rte *</type> <param>old</param></tagp> the previous route for the same network <tagp><type>rte *</type> <param>new_best</param></tagp> the new best route for the same network <tagp><type>rte *</type> <param>old_best</param></tagp> the previous best route for the same network <tagp><type>rte *</type> <param>before_old</param></tagp> The previous route before <param/old/ for the same network. If <param/before_old/ is NULL <param/old/ was the first. </descrip> <funcsect>Description This function gets a routing table update and announces it to all protocols that acccepts given type of route announcement and are connected to the same table by their announcement hooks. Route announcement of type <const/RA_OPTIMAL/ si generated when optimal route (in routing table <param/tab/) changes. In that case <param/old/ stores the old optimal route. Route announcement of type <const/RA_ANY/ si generated when any route (in routing table <param/tab/) changes In that case <param/old/ stores the old route from the same protocol. For each appropriate protocol, we first call its <func/import_control()/ hook which performs basic checks on the route (each protocol has a right to veto or force accept of the route before any filter is asked) and adds default values of attributes specific to the new protocol (metrics, tags etc.). Then it consults the protocol's export filter and if it accepts the route, the <func/rt_notify()/ hook of the protocol gets called. </function> <function><type>void</type> <funcdef>rte_free</funcdef> (<type>rte *</type> <param>e</param>) -- delete a <struct/rte/ <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>e</param></tagp> <struct/rte/ to be deleted </descrip> <funcsect>Description <func/rte_free()/ deletes the given <struct/rte/ from the routing table it's linked to. </function> <function><type>void</type> <funcdef>rte_update2</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct announce_hook *</type> <param>ah</param></tagp> pointer to table announce hook <tagp><type>net *</type> <param>net</param></tagp> network node <tagp><type>rte *</type> <param>new</param></tagp> a <struct/rte/ representing the new route or <const/NULL/ for route removal. <tagp><type>struct rte_src *</type> <param>src</param></tagp> protocol originating the update </descrip> <funcsect>Description This function is called by the routing protocols whenever they discover a new route or wish to update/remove an existing route. The right announcement sequence is to build route attributes first (either un-cached with <param/aflags/ set to zero or a cached one using <func/rta_lookup()/; in this case please note that you need to increase the use count of the attributes yourself by calling <func/rta_clone()/), call <func/rte_get_temp()/ to obtain a temporary <struct/rte/, fill in all the appropriate data and finally submit the new <struct/rte/ by calling <func/rte_update()/. <param/src/ specifies the protocol that originally created the route and the meaning of protocol-dependent data of <param/new/. If <param/new/ is not <const/NULL/, <param/src/ have to be the same value as <param/new/->attrs->proto. <param/p/ specifies the protocol that called <func/rte_update()/. In most cases it is the same protocol as <param/src/. <func/rte_update()/ stores <param/p/ in <param/new/->sender; When <func/rte_update()/ gets any route, it automatically validates it (checks, whether the network and next hop address are valid IP addresses and also whether a normal routing protocol doesn't try to smuggle a host or link scope route to the table), converts all protocol dependent attributes stored in the <struct/rte/ to temporary extended attributes, consults import filters of the protocol to see if the route should be accepted and/or its attributes modified, stores the temporary attributes back to the <struct/rte/. Now, having a "public" version of the route, we automatically find any old route defined by the protocol <param/src/ for network <param/n/, replace it by the new one (or removing it if <param/new/ is <const/NULL/), recalculate the optimal route for this destination and finally broadcast the change (if any) to all routing protocols by calling <func/rte_announce()/. All memory used for attribute lists and other temporary allocations is taken from a special linear pool <param/rte_update_pool/ and freed when <func/rte_update()/ finishes. </function> <function><type>void</type> <funcdef>rt_refresh_begin</funcdef> (<type>rtable *</type> <param>t</param>, <type>struct announce_hook *</type> <param>ah</param>) -- start a refresh cycle <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>t</param></tagp> related routing table <tagp><type>struct announce_hook *</type> <param>ah</param></tagp> related announce hook </descrip> <funcsect>Description This function starts a refresh cycle for given routing table and announce hook. The refresh cycle is a sequence where the protocol sends all its valid routes to the routing table (by <func/rte_update()/). After that, all protocol routes (more precisely routes with <param/ah/ as <param/sender/) not sent during the refresh cycle but still in the table from the past are pruned. This is implemented by marking all related routes as stale by REF_STALE flag in <func/rt_refresh_begin()/, then marking all related stale routes with REF_DISCARD flag in <func/rt_refresh_end()/ and then removing such routes in the prune loop. </function> <function><type>void</type> <funcdef>rt_refresh_end</funcdef> (<type>rtable *</type> <param>t</param>, <type>struct announce_hook *</type> <param>ah</param>) -- end a refresh cycle <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>t</param></tagp> related routing table <tagp><type>struct announce_hook *</type> <param>ah</param></tagp> related announce hook </descrip> <funcsect>Description This function starts a refresh cycle for given routing table and announce hook. See <func/rt_refresh_begin()/ for description of refresh cycles. </function> <function><type>void</type> <funcdef>rte_dump</funcdef> (<type>rte *</type> <param>e</param>) -- dump a route <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>e</param></tagp> <struct/rte/ to be dumped </descrip> <funcsect>Description This functions dumps contents of a <struct/rte/ to debug output. </function> <function><type>void</type> <funcdef>rt_dump</funcdef> (<type>rtable *</type> <param>t</param>) -- dump a routing table <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>t</param></tagp> routing table to be dumped </descrip> <funcsect>Description This function dumps contents of a given routing table to debug output. </function> <function><type>void</type> <funcdef>rt_dump_all</funcdef> (<param>void</param>) -- dump all routing tables <funcsect>Description This function dumps contents of all routing tables to debug output. </function> <function><type>void</type> <funcdef>rt_init</funcdef> (<param>void</param>) -- initialize routing tables <funcsect>Description This function is called during BIRD startup. It initializes the routing table module. </function> <function><type>int</type> <funcdef>rt_prune_table</funcdef> (<type>rtable *</type> <param>tab</param>) -- prune a routing table <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>tab</param></tagp> a routing table for pruning </descrip> <funcsect>Description This function scans the routing table <param/tab/ and removes routes belonging to flushing protocols, discarded routes and also stale network entries, in a similar fashion like <func/rt_prune_loop()/. Returns 1 when all such routes are pruned. Contrary to <func/rt_prune_loop()/, this function is not a part of the protocol flushing loop, but it is called from <func/rt_event()/ for just one routing table. Note that <func/rt_prune_table()/ and <func/rt_prune_loop()/ share (for each table) the prune state (<param/prune_state/) and also the pruning iterator (<param/prune_fit/). </function> <function><type>int</type> <funcdef>rt_prune_loop</funcdef> (<param>void</param>) -- prune routing tables <funcsect>Description The prune loop scans routing tables and removes routes belonging to flushing protocols, discarded routes and also stale network entries. Returns 1 when all such routes are pruned. It is a part of the protocol flushing loop. </function> <function><type>void</type> <funcdef>rt_lock_table</funcdef> (<type>rtable *</type> <param>r</param>) -- lock a routing table <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>r</param></tagp> routing table to be locked </descrip> <funcsect>Description Lock a routing table, because it's in use by a protocol, preventing it from being freed when it gets undefined in a new configuration. </function> <function><type>void</type> <funcdef>rt_unlock_table</funcdef> (<type>rtable *</type> <param>r</param>) -- unlock a routing table <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>r</param></tagp> routing table to be unlocked </descrip> <funcsect>Description Unlock a routing table formerly locked by <func/rt_lock_table()/, that is decrease its use count and delete it if it's scheduled for deletion by configuration changes. </function> <function><type>void</type> <funcdef>rt_commit</funcdef> (<type>struct config *</type> <param>new</param>, <type>struct config *</type> <param>old</param>) -- commit new routing table configuration <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>new</param></tagp> new configuration <tagp><type>struct config *</type> <param>old</param></tagp> original configuration or <const/NULL/ if it's boot time config </descrip> <funcsect>Description Scan differences between <param/old/ and <param/new/ configuration and modify the routing tables according to these changes. If <param/new/ defines a previously unknown table, create it, if it omits a table existing in <param/old/, schedule it for deletion (it gets deleted when all protocols disconnect from it by calling <func/rt_unlock_table()/), if it exists in both configurations, leave it unchanged. </function> <function><type>int</type> <funcdef>rt_feed_baby</funcdef> (<type>struct proto *</type> <param>p</param>) -- advertise routes to a new protocol <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol to be fed </descrip> <funcsect>Description This function performs one pass of advertisement of routes to a newly initialized protocol. It's called by the protocol code as long as it has something to do. (We avoid transferring all the routes in single pass in order not to monopolize CPU time.) </function> <function><type>void</type> <funcdef>rt_feed_baby_abort</funcdef> (<type>struct proto *</type> <param>p</param>) -- abort protocol feeding <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol </descrip> <funcsect>Description This function is called by the protocol code when the protocol stops or ceases to exist before the last iteration of <func/rt_feed_baby()/ has finished. </function> <function><type>net *</type> <funcdef>net_find</funcdef> (<type>rtable *</type> <param>tab</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>len</param>) -- find a network entry <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>tab</param></tagp> a routing table <tagp><type>ip_addr</type> <param>addr</param></tagp> address of the network <tagp><type>unsigned</type> <param>len</param></tagp> length of the network prefix </descrip> <funcsect>Description <func/net_find()/ looks up the given network in routing table <param/tab/ and returns a pointer to its <struct/net/ entry or <const/NULL/ if no such network exists. </function> <function><type>net *</type> <funcdef>net_get</funcdef> (<type>rtable *</type> <param>tab</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>len</param>) -- obtain a network entry <funcsect>Arguments <descrip> <tagp><type>rtable *</type> <param>tab</param></tagp> a routing table <tagp><type>ip_addr</type> <param>addr</param></tagp> address of the network <tagp><type>unsigned</type> <param>len</param></tagp> length of the network prefix </descrip> <funcsect>Description <func/net_get()/ looks up the given network in routing table <param/tab/ and returns a pointer to its <struct/net/ entry. If no such entry exists, it's created. </function> <function><type>rte *</type> <funcdef>rte_cow</funcdef> (<type>rte *</type> <param>r</param>) -- copy a route for writing <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>r</param></tagp> a route entry to be copied </descrip> <funcsect>Description <func/rte_cow()/ takes a <struct/rte/ and prepares it for modification. The exact action taken depends on the flags of the <struct/rte/ -- if it's a temporary entry, it's just returned unchanged, else a new temporary entry with the same contents is created. The primary use of this function is inside the filter machinery -- when a filter wants to modify <struct/rte/ contents (to change the preference or to attach another set of attributes), it must ensure that the <struct/rte/ is not shared with anyone else (and especially that it isn't stored in any routing table). <funcsect>Result a pointer to the new writable <struct/rte/. </function> <sect>Route attribute cache Each route entry carries a set of route attributes. Several of them vary from route to route, but most attributes are usually common for a large number of routes. To conserve memory, we've decided to store only the varying ones directly in the <struct/rte/ and hold the rest in a special structure called <struct/rta/ which is shared among all the <struct/rte/'s with these attributes. Each <struct/rta/ contains all the static attributes of the route (i.e., those which are always present) as structure members and a list of dynamic attributes represented by a linked list of <struct/ea_list/ structures, each of them consisting of an array of <struct/eattr/'s containing the individual attributes. An attribute can be specified more than once in the <struct/ea_list/ chain and in such case the first occurrence overrides the others. This semantics is used especially when someone (for example a filter) wishes to alter values of several dynamic attributes, but it wants to preserve the original attribute lists maintained by another module. Each <struct/eattr/ contains an attribute identifier (split to protocol ID and per-protocol attribute ID), protocol dependent flags, a type code (consisting of several bit fields describing attribute characteristics) and either an embedded 32-bit value or a pointer to a <struct/adata/ structure holding attribute contents. There exist two variants of <struct/rta/'s -- cached and un-cached ones. Un-cached <struct/rta/'s can have arbitrarily complex structure of <struct/ea_list/'s and they can be modified by any module in the route processing chain. Cached <struct/rta/'s have their attribute lists normalized (that means at most one <struct/ea_list/ is present and its values are sorted in order to speed up searching), they are stored in a hash table to make fast lookup possible and they are provided with a use count to allow sharing. Routing tables always contain only cached <struct/rta/'s. <function><type>struct mpnh *</type> <funcdef>mpnh_merge</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct mpnh *</type> <param>x</param></tagp> list 1 <tagp><type>struct mpnh *</type> <param>y</param></tagp> list 2 <tagp><type>int</type> <param>rx</param></tagp> reusability of list <param/x/ <tagp><type>int</type> <param>ry</param></tagp> reusability of list <param/y/ <tagp><type>int</type> <param>max</param></tagp> max number of nexthops <tagp><type>linpool *</type> <param>lp</param></tagp> linpool for allocating nexthops </descrip> <funcsect>Description The <func/mpnh_merge()/ function takes two nexthop lists <param/x/ and <param/y/ and merges them, eliminating possible duplicates. The input lists must be sorted and the result is sorted too. The number of nexthops in result is limited by <param/max/. New nodes are allocated from linpool <param/lp/. The arguments <param/rx/ and <param/ry/ specify whether corresponding input lists may be consumed by the function (i.e. their nodes reused in the resulting list), in that case the caller should not access these lists after that. To eliminate issues with deallocation of these lists, the caller should use some form of bulk deallocation (e.g. stack or linpool) to free these nodes when the resulting list is no longer needed. When reusability is not set, the corresponding lists are not modified nor linked from the resulting list. </function> <function><type>eattr *</type> <funcdef>ea_find</funcdef> (<type>ea_list *</type> <param>e</param>, <type>unsigned</type> <param>id</param>) -- find an extended attribute <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>e</param></tagp> attribute list to search in <tagp><type>unsigned</type> <param>id</param></tagp> attribute ID to search for </descrip> <funcsect>Description Given an extended attribute list, <func/ea_find()/ searches for a first occurrence of an attribute with specified ID, returning either a pointer to its <struct/eattr/ structure or <const/NULL/ if no such attribute exists. </function> <function><type>eattr *</type> <funcdef>ea_walk</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct ea_walk_state *</type> <param>s</param></tagp> walk state structure <tagp><type>uint</type> <param>id</param></tagp> start of attribute ID interval <tagp><type>uint</type> <param>max</param></tagp> length of attribute ID interval </descrip> <funcsect>Description Given an extended attribute list, <func/ea_walk()/ walks through the list looking for first occurrences of attributes with ID in specified interval from <param/id/ to (<param/id/ + <param/max/ - 1), returning pointers to found <struct/eattr/ structures, storing its walk state in <param/s/ for subsequent calls. The function <func/ea_walk()/ is supposed to be called in a loop, with initially zeroed walk state structure <param/s/ with filled the initial extended attribute list, returning one found attribute in each call or <const/NULL/ when no other attribute exists. The extended attribute list or the arguments should not be modified between calls. The maximum value of <param/max/ is 128. </function> <function><type>int</type> <funcdef>ea_get_int</funcdef> (<type>ea_list *</type> <param>e</param>, <type>unsigned</type> <param>id</param>, <type>int</type> <param>def</param>) -- fetch an integer attribute <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>e</param></tagp> attribute list <tagp><type>unsigned</type> <param>id</param></tagp> attribute ID <tagp><type>int</type> <param>def</param></tagp> default value </descrip> <funcsect>Description This function is a shortcut for retrieving a value of an integer attribute by calling <func/ea_find()/ to find the attribute, extracting its value or returning a provided default if no such attribute is present. </function> <function><type>void</type> <funcdef>ea_sort</funcdef> (<type>ea_list *</type> <param>e</param>) -- sort an attribute list <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>e</param></tagp> list to be sorted </descrip> <funcsect>Description This function takes a <struct/ea_list/ chain and sorts the attributes within each of its entries. If an attribute occurs multiple times in a single <struct/ea_list/, <func/ea_sort()/ leaves only the first (the only significant) occurrence. </function> <function><type>unsigned</type> <funcdef>ea_scan</funcdef> (<type>ea_list *</type> <param>e</param>) -- estimate attribute list size <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>e</param></tagp> attribute list </descrip> <funcsect>Description This function calculates an upper bound of the size of a given <struct/ea_list/ after merging with <func/ea_merge()/. </function> <function><type>void</type> <funcdef>ea_merge</funcdef> (<type>ea_list *</type> <param>e</param>, <type>ea_list *</type> <param>t</param>) -- merge segments of an attribute list <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>e</param></tagp> attribute list <tagp><type>ea_list *</type> <param>t</param></tagp> buffer to store the result to </descrip> <funcsect>Description This function takes a possibly multi-segment attribute list and merges all of its segments to one. The primary use of this function is for <struct/ea_list/ normalization: first call <func/ea_scan()/ to determine how much memory will the result take, then allocate a buffer (usually using <func/alloca()/), merge the segments with <func/ea_merge()/ and finally sort and prune the result by calling <func/ea_sort()/. </function> <function><type>int</type> <funcdef>ea_same</funcdef> (<type>ea_list *</type> <param>x</param>, <type>ea_list *</type> <param>y</param>) -- compare two <struct/ea_list/'s <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>x</param></tagp> attribute list <tagp><type>ea_list *</type> <param>y</param></tagp> attribute list </descrip> <funcsect>Description <func/ea_same()/ compares two normalized attribute lists <param/x/ and <param/y/ and returns 1 if they contain the same attributes, 0 otherwise. </function> <function><type>void</type> <funcdef>ea_show</funcdef> (<type>struct cli *</type> <param>c</param>, <type>eattr *</type> <param>e</param>) -- print an <struct/eattr/ to CLI <funcsect>Arguments <descrip> <tagp><type>struct cli *</type> <param>c</param></tagp> destination CLI <tagp><type>eattr *</type> <param>e</param></tagp> attribute to be printed </descrip> <funcsect>Description This function takes an extended attribute represented by its <struct/eattr/ structure and prints it to the CLI according to the type information. If the protocol defining the attribute provides its own <func/get_attr()/ hook, it's consulted first. </function> <function><type>void</type> <funcdef>ea_dump</funcdef> (<type>ea_list *</type> <param>e</param>) -- dump an extended attribute <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>e</param></tagp> attribute to be dumped </descrip> <funcsect>Description <func/ea_dump()/ dumps contents of the extended attribute given to the debug output. </function> <function><type>uint</type> <funcdef>ea_hash</funcdef> (<type>ea_list *</type> <param>e</param>) -- calculate an <struct/ea_list/ hash key <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>e</param></tagp> attribute list </descrip> <funcsect>Description <func/ea_hash()/ takes an extended attribute list and calculated a hopefully uniformly distributed hash value from its contents. </function> <function><type>ea_list *</type> <funcdef>ea_append</funcdef> (<type>ea_list *</type> <param>to</param>, <type>ea_list *</type> <param>what</param>) -- concatenate <struct/ea_list/'s <funcsect>Arguments <descrip> <tagp><type>ea_list *</type> <param>to</param></tagp> destination list (can be <const/NULL/) <tagp><type>ea_list *</type> <param>what</param></tagp> list to be appended (can be <const/NULL/) </descrip> <funcsect>Description This function appends the <struct/ea_list/ <param/what/ at the end of <struct/ea_list/ <param/to/ and returns a pointer to the resulting list. </function> <function><type>rta *</type> <funcdef>rta_lookup</funcdef> (<type>rta *</type> <param>o</param>) -- look up a <struct/rta/ in attribute cache <funcsect>Arguments <descrip> <tagp><type>rta *</type> <param>o</param></tagp> a un-cached <struct/rta/ </descrip> <funcsect>Description <func/rta_lookup()/ gets an un-cached <struct/rta/ structure and returns its cached counterpart. It starts with examining the attribute cache to see whether there exists a matching entry. If such an entry exists, it's returned and its use count is incremented, else a new entry is created with use count set to 1. The extended attribute lists attached to the <struct/rta/ are automatically converted to the normalized form. </function> <function><type>void</type> <funcdef>rta_dump</funcdef> (<type>rta *</type> <param>a</param>) -- dump route attributes <funcsect>Arguments <descrip> <tagp><type>rta *</type> <param>a</param></tagp> attribute structure to dump </descrip> <funcsect>Description This function takes a <struct/rta/ and dumps its contents to the debug output. </function> <function><type>void</type> <funcdef>rta_dump_all</funcdef> (<param>void</param>) -- dump attribute cache <funcsect>Description This function dumps the whole contents of route attribute cache to the debug output. </function> <function><type>void</type> <funcdef>rta_init</funcdef> (<param>void</param>) -- initialize route attribute cache <funcsect>Description This function is called during initialization of the routing table module to set up the internals of the attribute cache. </function> <function><type>rta *</type> <funcdef>rta_clone</funcdef> (<type>rta *</type> <param>r</param>) -- clone route attributes <funcsect>Arguments <descrip> <tagp><type>rta *</type> <param>r</param></tagp> a <struct/rta/ to be cloned </descrip> <funcsect>Description <func/rta_clone()/ takes a cached <struct/rta/ and returns its identical cached copy. Currently it works by just returning the original <struct/rta/ with its use count incremented. </function> <function><type>void</type> <funcdef>rta_free</funcdef> (<type>rta *</type> <param>r</param>) -- free route attributes <funcsect>Arguments <descrip> <tagp><type>rta *</type> <param>r</param></tagp> a <struct/rta/ to be freed </descrip> <funcsect>Description If you stop using a <struct/rta/ (for example when deleting a route which uses it), you need to call <func/rta_free()/ to notify the attribute cache the attribute is no longer in use and can be freed if you were the last user (which <func/rta_free()/ tests by inspecting the use count). </function>  <sect>Routing protocols <sect1>Introduction The routing protocols are the bird's heart and a fine amount of code is dedicated to their management and for providing support functions to them. (-: Actually, this is the reason why the directory with sources of the core code is called <tt/nest/ :-). When talking about protocols, one need to distinguish between <em/protocols/ and protocol <em/instances/. A protocol exists exactly once, not depending on whether it's configured or not and it can have an arbitrary number of instances corresponding to its "incarnations" requested by the configuration file. Each instance is completely autonomous, has its own configuration, its own status, its own set of routes and its own set of interfaces it works on. A protocol is represented by a <struct/protocol/ structure containing all the basic information (protocol name, default settings and pointers to most of the protocol hooks). All these structures are linked in the <param/protocol_list/ list. Each instance has its own <struct/proto/ structure describing all its properties: protocol type, configuration, a resource pool where all resources belonging to the instance live, various protocol attributes (take a look at the declaration of <struct/proto/ in <tt/protocol.h/), protocol states (see below for what do they mean), connections to routing tables, filters attached to the protocol and finally a set of pointers to the rest of protocol hooks (they are the same for all instances of the protocol, but in order to avoid extra indirections when calling the hooks from the fast path, they are stored directly in <struct/proto/). The instance is always linked in both the global instance list (<param/proto_list/) and a per-status list (either <param/active_proto_list/ for running protocols, <param/initial_proto_list/ for protocols being initialized or <param/flush_proto_list/ when the protocol is being shut down). The protocol hooks are described in the next chapter, for more information about configuration of protocols, please refer to the configuration chapter and also to the description of the <func/proto_commit/ function. <sect1>Protocol states As startup and shutdown of each protocol are complex processes which can be affected by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.), we have decided to supervise them by a pair of simple state machines -- the protocol state machine and a core state machine. The <em/protocol state machine/ corresponds to internal state of the protocol and the protocol can alter its state whenever it wants to. There are the following states: <descrip> <tag/PS_DOWN/ The protocol is down and waits for being woken up by calling its start() hook. <tag/PS_START/ The protocol is waiting for connection with the rest of the network. It's active, it has resources allocated, but it still doesn't want any routes since it doesn't know what to do with them. <tag/PS_UP/ The protocol is up and running. It communicates with the core, delivers routes to tables and wants to hear announcement about route changes. <tag/PS_STOP/ The protocol has been shut down (either by being asked by the core code to do so or due to having encountered a protocol error). </descrip> Unless the protocol is in the <tt/PS_DOWN/ state, it can decide to change its state by calling the <func/proto_notify_state/ function. At any time, the core code can ask the protocol to shut itself down by calling its stop() hook. The <em/core state machine/ takes care of the core view of protocol state. The states are traversed according to changes of the protocol state machine, but sometimes the transitions are delayed if the core needs to finish some actions (for example sending of new routes to the protocol) before proceeding to the new state. There are the following core states: <descrip> <tag/FS_HUNGRY/ The protocol is down, it doesn't have any routes and doesn't want them. <tag/FS_FEEDING/ The protocol has reached the <tt/PS_UP/ state, but we are still busy sending the initial set of routes to it. <tag/FS_HAPPY/ The protocol is up and has complete routing information. <tag/FS_FLUSHING/ The protocol is shutting down (it's in either <tt/PS_STOP/ or <tt/PS_DOWN/ state) and we're flushing all of its routes from the routing tables. </descrip> <sect1>Functions of the protocol module The protocol module provides the following functions: <function><type>void *</type> <funcdef>proto_new</funcdef> (<type>struct proto_config *</type> <param>c</param>, <type>unsigned</type> <param>size</param>) -- create a new protocol instance <funcsect>Arguments <descrip> <tagp><type>struct proto_config *</type> <param>c</param></tagp> protocol configuration <tagp><type>unsigned</type> <param>size</param></tagp> size of protocol data structure (each protocol instance is represented by a structure starting with generic part [struct <struct/proto/] and continued with data specific to the protocol) </descrip> <funcsect>Description When a new configuration has been read in, the core code starts initializing all the protocol instances configured by calling their <func/init()/ hooks with the corresponding instance configuration. The initialization code of the protocol is expected to create a new instance according to the configuration by calling this function and then modifying the default settings to values wanted by the protocol. </function> <function><type>struct announce_hook *</type> <funcdef>proto_add_announce_hook</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance <tagp><type>struct rtable *</type> <param>t</param></tagp> routing table to connect to <tagp><type>struct proto_stats *</type> <param>stats</param></tagp> per-table protocol statistics </descrip> <funcsect>Description This function creates a connection between the protocol instance <param/p/ and the routing table <param/t/, making the protocol hear all changes in the table. The announce hook is linked in the protocol ahook list. Announce hooks are allocated from the routing table resource pool and when protocol accepts routes also in the table ahook list. The are linked to the table ahook list and unlinked from it depending on export_state (in <func/proto_want_export_up()/ and <func/proto_want_export_down()/) and they are automatically freed after the protocol is flushed (in <func/proto_fell_down()/). Unless you want to listen to multiple routing tables (as the Pipe protocol does), you needn't to worry about this function since the connection to the protocol's primary routing table is initialized automatically by the core code. </function> <function><type>struct announce_hook *</type> <funcdef>proto_find_announce_hook</funcdef> (<type>struct proto *</type> <param>p</param>, <type>struct rtable *</type> <param>t</param>) -- find announce hooks <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance <tagp><type>struct rtable *</type> <param>t</param></tagp> routing table </descrip> <funcsect>Description Returns pointer to announce hook or NULL </function> <function><type>void *</type> <funcdef>proto_config_new</funcdef> (<type>struct protocol *</type> <param>pr</param>, <type>int</type> <param>class</param>) -- create a new protocol configuration <funcsect>Arguments <descrip> <tagp><type>struct protocol *</type> <param>pr</param></tagp> protocol the configuration will belong to <tagp><type>int</type> <param>class</param></tagp> SYM_PROTO or SYM_TEMPLATE </descrip> <funcsect>Description Whenever the configuration file says that a new instance of a routing protocol should be created, the parser calls <func/proto_config_new()/ to create a configuration entry for this instance (a structure staring with the <struct/proto_config/ header containing all the generic items followed by protocol-specific ones). Also, the configuration entry gets added to the list of protocol instances kept in the configuration. The function is also used to create protocol templates (when class SYM_TEMPLATE is specified), the only difference is that templates are not added to the list of protocol instances and therefore not initialized during <func/protos_commit()/). </function> <function><type>void</type> <funcdef>proto_copy_config</funcdef> (<type>struct proto_config *</type> <param>dest</param>, <type>struct proto_config *</type> <param>src</param>) -- copy a protocol configuration <funcsect>Arguments <descrip> <tagp><type>struct proto_config *</type> <param>dest</param></tagp> destination protocol configuration <tagp><type>struct proto_config *</type> <param>src</param></tagp> source protocol configuration </descrip> <funcsect>Description Whenever a new instance of a routing protocol is created from the template, <func/proto_copy_config()/ is called to copy a content of the source protocol configuration to the new protocol configuration. Name, class and a node in protos list of <param/dest/ are kept intact. <func/copy_config()/ protocol hook is used to copy protocol-specific data. </function> <function><type>void</type> <funcdef>protos_preconfig</funcdef> (<type>struct config *</type> <param>c</param>) -- pre-configuration processing <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>c</param></tagp> new configuration </descrip> <funcsect>Description This function calls the <func/preconfig()/ hooks of all routing protocols available to prepare them for reading of the new configuration. </function> <function><type>void</type> <funcdef>protos_postconfig</funcdef> (<type>struct config *</type> <param>c</param>) -- post-configuration processing <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>c</param></tagp> new configuration </descrip> <funcsect>Description This function calls the <func/postconfig()/ hooks of all protocol instances specified in configuration <param/c/. The hooks are not called for protocol templates. </function> <function><type>void</type> <funcdef>protos_commit</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>new</param></tagp> new configuration <tagp><type>struct config *</type> <param>old</param></tagp> old configuration or <const/NULL/ if it's boot time config <tagp><type>int</type> <param>force_reconfig</param></tagp> force restart of all protocols (used for example when the router ID changes) <tagp><type>int</type> <param>type</param></tagp> type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD) </descrip> <funcsect>Description Scan differences between <param/old/ and <param/new/ configuration and adjust all protocol instances to conform to the new configuration. When a protocol exists in the new configuration, but it doesn't in the original one, it's immediately started. When a collision with the other running protocol would arise, the new protocol will be temporarily stopped by the locking mechanism. When a protocol exists in the old configuration, but it doesn't in the new one, it's shut down and deleted after the shutdown completes. When a protocol exists in both configurations, the core decides whether it's possible to reconfigure it dynamically - it checks all the core properties of the protocol (changes in filters are ignored if type is RECONFIG_SOFT) and if they match, it asks the <func/reconfigure()/ hook of the protocol to see if the protocol is able to switch to the new configuration. If it isn't possible, the protocol is shut down and a new instance is started with the new configuration after the shutdown is completed. </function> <sect>Graceful restart recovery Graceful restart of a router is a process when the routing plane (e.g. BIRD) restarts but both the forwarding plane (e.g kernel routing table) and routing neighbors keep proper routes, and therefore uninterrupted packet forwarding is maintained. BIRD implements graceful restart recovery by deferring export of routes to protocols until routing tables are refilled with the expected content. After start, protocols generate routes as usual, but routes are not propagated to them, until protocols report that they generated all routes. After that, graceful restart recovery is finished and the export (and the initial feed) to protocols is enabled. When graceful restart recovery need is detected during initialization, then enabled protocols are marked with <param/gr_recovery/ flag before start. Such protocols then decide how to proceed with graceful restart, participation is voluntary. Protocols could lock the recovery by <func/proto_graceful_restart_lock()/ (stored in <param/gr_lock/ flag), which means that they want to postpone the end of the recovery until they converge and then unlock it. They also could set <param/gr_wait/ before advancing to <const/PS_UP/, which means that the core should defer route export to that protocol until the end of the recovery. This should be done by protocols that expect their neigbors to keep the proper routes (kernel table, BGP sessions with BGP graceful restart capability). The graceful restart recovery is finished when either all graceful restart locks are unlocked or when graceful restart wait timer fires. <function><type>void</type> <funcdef>graceful_restart_recovery</funcdef> (<param>void</param>) -- request initial graceful restart recovery <funcsect>Graceful restart recovery Called by the platform initialization code if the need for recovery after graceful restart is detected during boot. Have to be called before <func/protos_commit()/. </function> <function><type>void</type> <funcdef>graceful_restart_init</funcdef> (<param>void</param>) -- initialize graceful restart <funcsect>Description When graceful restart recovery was requested, the function starts an active phase of the recovery and initializes graceful restart wait timer. The function have to be called after <func/protos_commit()/. </function> <function><type>void</type> <funcdef>graceful_restart_done</funcdef> (<type>struct timer *t</type> <param>UNUSED</param>) -- finalize graceful restart <funcsect>Arguments <descrip> <tagp><type>struct timer *t</type> <param>UNUSED</param></tagp> -- undescribed -- </descrip> <funcsect>Description When there are no locks on graceful restart, the functions finalizes the graceful restart recovery. Protocols postponing route export until the end of the recovery are awakened and the export to them is enabled. All other related state is cleared. The function is also called when the graceful restart wait timer fires (but there are still some locks). </function> <function><type>void</type> <funcdef>proto_graceful_restart_lock</funcdef> (<type>struct proto *</type> <param>p</param>) -- lock graceful restart by protocol <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance </descrip> <funcsect>Description This function allows a protocol to postpone the end of graceful restart recovery until it converges. The lock is removed when the protocol calls <func/proto_graceful_restart_unlock()/ or when the protocol is stopped. The function have to be called during the initial phase of graceful restart recovery and only for protocols that are part of graceful restart (i.e. their <param/gr_recovery/ is set), which means it should be called from protocol start hooks. </function> <function><type>void</type> <funcdef>proto_graceful_restart_unlock</funcdef> (<type>struct proto *</type> <param>p</param>) -- unlock graceful restart by protocol <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance </descrip> <funcsect>Description This function unlocks a lock from <func/proto_graceful_restart_lock()/. It is also automatically called when the lock holding protocol went down. </function> <function><type>void</type> <funcdef>protos_dump_all</funcdef> (<param>void</param>) -- dump status of all protocols <funcsect>Description This function dumps status of all existing protocol instances to the debug output. It involves printing of general status information such as protocol states, its position on the protocol lists and also calling of a <func/dump()/ hook of the protocol to print the internals. </function> <function><type>void</type> <funcdef>proto_build</funcdef> (<type>struct protocol *</type> <param>p</param>) -- make a single protocol available <funcsect>Arguments <descrip> <tagp><type>struct protocol *</type> <param>p</param></tagp> the protocol </descrip> <funcsect>Description After the platform specific initialization code uses <func/protos_build()/ to add all the standard protocols, it should call <func/proto_build()/ for all platform specific protocols to inform the core that they exist. </function> <function><type>void</type> <funcdef>protos_build</funcdef> (<param>void</param>) -- build a protocol list <funcsect>Description This function is called during BIRD startup to insert all standard protocols to the global protocol list. Insertion of platform specific protocols (such as the kernel syncer) is in the domain of competence of the platform dependent startup code. </function> <function><type>void</type> <funcdef>proto_set_message</funcdef> (<type>struct proto *</type> <param>p</param>, <type>char *</type> <param>msg</param>, <type>int</type> <param>len</param>) -- set administrative message to protocol <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol <tagp><type>char *</type> <param>msg</param></tagp> message <tagp><type>int</type> <param>len</param></tagp> message length (-1 for NULL-terminated string) </descrip> <funcsect>Description The function sets administrative message (string) related to protocol state change. It is called by the nest code for manual enable/disable/restart commands all routes to the protocol, and by protocol-specific code when the protocol state change is initiated by the protocol. Using NULL message clears the last message. The message string may be either NULL-terminated or with an explicit length. </function> <function><type>void</type> <funcdef>proto_request_feeding</funcdef> (<type>struct proto *</type> <param>p</param>) -- request feeding routes to the protocol <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> given protocol </descrip> <funcsect>Description Sometimes it is needed to send again all routes to the protocol. This is called feeding and can be requested by this function. This would cause protocol export state transition to ES_FEEDING (during feeding) and when completed, it will switch back to ES_READY. This function can be called even when feeding is already running, in that case it is restarted. </function> <function><type>void</type> <funcdef>proto_notify_limit</funcdef> (<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>) <funcsect>Arguments <descrip> <tagp><type>struct announce_hook *</type> <param>ah</param></tagp> announce hook <tagp><type>struct proto_limit *</type> <param>l</param></tagp> limit being hit <tagp><type>int</type> <param>dir</param></tagp> limit direction (PLD_*) <tagp><type>u32</type> <param>rt_count</param></tagp> the number of routes </descrip> <funcsect>Description The function is called by the route processing core when limit <param/l/ is breached. It activates the limit and tooks appropriate action according to <param/l/->action. </function> <function><type>void</type> <funcdef>proto_notify_state</funcdef> (<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>ps</param>) -- notify core about protocol state change <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol the state of which has changed <tagp><type>unsigned</type> <param>ps</param></tagp> the new status </descrip> <funcsect>Description Whenever a state of a protocol changes due to some event internal to the protocol (i.e., not inside a <func/start()/ or <func/shutdown()/ hook), it should immediately notify the core about the change by calling <func/proto_notify_state()/ which will write the new state to the <struct/proto/ structure and take all the actions necessary to adapt to the new state. State change to PS_DOWN immediately frees resources of protocol and might execute start callback of protocol; therefore, it should be used at tail positions of protocol callbacks. </function> <sect>Protocol hooks Each protocol can provide a rich set of hook functions referred to by pointers in either the <struct/proto/ or <struct/protocol/ structure. They are called by the core whenever it wants the protocol to perform some action or to notify the protocol about any change of its environment. All of the hooks can be set to <const/NULL/ which means to ignore the change or to take a default action. <function><type>void</type> <funcdef>preconfig</funcdef> (<type>struct protocol *</type> <param>p</param>, <type>struct config *</type> <param>c</param>) -- protocol preconfiguration <funcsect>Arguments <descrip> <tagp><type>struct protocol *</type> <param>p</param></tagp> a routing protocol <tagp><type>struct config *</type> <param>c</param></tagp> new configuration </descrip> <funcsect>Description The <func/preconfig()/ hook is called before parsing of a new configuration. </function> <function><type>void</type> <funcdef>postconfig</funcdef> (<type>struct proto_config *</type> <param>c</param>) -- instance post-configuration <funcsect>Arguments <descrip> <tagp><type>struct proto_config *</type> <param>c</param></tagp> instance configuration </descrip> <funcsect>Description The <func/postconfig()/ hook is called for each configured instance after parsing of the new configuration is finished. </function> <function><type>struct proto *</type> <funcdef>init</funcdef> (<type>struct proto_config *</type> <param>c</param>) -- initialize an instance <funcsect>Arguments <descrip> <tagp><type>struct proto_config *</type> <param>c</param></tagp> instance configuration </descrip> <funcsect>Description The <func/init()/ hook is called by the core to create a protocol instance according to supplied protocol configuration. <funcsect>Result a pointer to the instance created </function> <function><type>int</type> <funcdef>reconfigure</funcdef> (<type>struct proto *</type> <param>p</param>, <type>struct proto_config *</type> <param>c</param>) -- request instance reconfiguration <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> an instance <tagp><type>struct proto_config *</type> <param>c</param></tagp> new configuration </descrip> <funcsect>Description The core calls the <func/reconfigure()/ hook whenever it wants to ask the protocol for switching to a new configuration. If the reconfiguration is possible, the hook returns 1. Otherwise, it returns 0 and the core will shut down the instance and start a new one with the new configuration. After the protocol confirms reconfiguration, it must no longer keep any references to the old configuration since the memory it's stored in can be re-used at any time. </function> <function><type>void</type> <funcdef>dump</funcdef> (<type>struct proto *</type> <param>p</param>) -- dump protocol state <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> an instance </descrip> <funcsect>Description This hook dumps the complete state of the instance to the debug output. </function> <function><type>void</type> <funcdef>dump_attrs</funcdef> (<type>rte *</type> <param>e</param>) -- dump protocol-dependent attributes <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>e</param></tagp> a route entry </descrip> <funcsect>Description This hook dumps all attributes in the <struct/rte/ which belong to this protocol to the debug output. </function> <function><type>int</type> <funcdef>start</funcdef> (<type>struct proto *</type> <param>p</param>) -- request instance startup <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance </descrip> <funcsect>Description The <func/start()/ hook is called by the core when it wishes to start the instance. Multitable protocols should lock their tables here. <funcsect>Result new protocol state </function> <function><type>int</type> <funcdef>shutdown</funcdef> (<type>struct proto *</type> <param>p</param>) -- request instance shutdown <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance </descrip> <funcsect>Description The <func/stop()/ hook is called by the core when it wishes to shut the instance down for some reason. <funcsect>Returns new protocol state </function> <function><type>void</type> <funcdef>cleanup</funcdef> (<type>struct proto *</type> <param>p</param>) -- request instance cleanup <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance </descrip> <funcsect>Description The <func/cleanup()/ hook is called by the core when the protocol became hungry/down, i.e. all protocol ahooks and routes are flushed. Multitable protocols should unlock their tables here. </function> <function><type>void</type> <funcdef>get_status</funcdef> (<type>struct proto *</type> <param>p</param>, <type>byte *</type> <param>buf</param>) -- get instance status <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance <tagp><type>byte *</type> <param>buf</param></tagp> buffer to be filled with the status string </descrip> <funcsect>Description This hook is called by the core if it wishes to obtain an brief one-line user friendly representation of the status of the instance to be printed by the <cf/show protocols/ command. </function> <function><type>void</type> <funcdef>get_route_info</funcdef> (<type>rte *</type> <param>e</param>, <type>byte *</type> <param>buf</param>, <type>ea_list *</type> <param>attrs</param>) -- get route information <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>e</param></tagp> a route entry <tagp><type>byte *</type> <param>buf</param></tagp> buffer to be filled with the resulting string <tagp><type>ea_list *</type> <param>attrs</param></tagp> extended attributes of the route </descrip> <funcsect>Description This hook is called to fill the buffer <param/buf/ with a brief user friendly representation of metrics of a route belonging to this protocol. </function> <function><type>int</type> <funcdef>get_attr</funcdef> (<type>eattr *</type> <param>a</param>, <type>byte *</type> <param>buf</param>, <type>int</type> <param>buflen</param>) -- get attribute information <funcsect>Arguments <descrip> <tagp><type>eattr *</type> <param>a</param></tagp> an extended attribute <tagp><type>byte *</type> <param>buf</param></tagp> buffer to be filled with attribute information <tagp><type>int</type> <param>buflen</param></tagp> a length of the <param/buf/ parameter </descrip> <funcsect>Description The <func/get_attr()/ hook is called by the core to obtain a user friendly representation of an extended route attribute. It can either leave the whole conversion to the core (by returning <const/GA_UNKNOWN/), fill in only attribute name (and let the core format the attribute value automatically according to the type field; by returning <const/GA_NAME/) or doing the whole conversion (used in case the value requires extra care; return <const/GA_FULL/). </function> <function><type>void</type> <funcdef>if_notify</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance <tagp><type>unsigned</type> <param>flags</param></tagp> interface change flags <tagp><type>struct iface *</type> <param>i</param></tagp> the interface in question </descrip> <funcsect>Description This hook is called whenever any network interface changes its status. The change is described by a combination of status bits (<const/IF_CHANGE_xxx/) in the <param/flags/ parameter. </function> <function><type>void</type> <funcdef>ifa_notify</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance <tagp><type>unsigned</type> <param>flags</param></tagp> address change flags <tagp><type>struct ifa *</type> <param>a</param></tagp> the interface address </descrip> <funcsect>Description This hook is called to notify the protocol instance about an interface acquiring or losing one of its addresses. The change is described by a combination of status bits (<const/IF_CHANGE_xxx/) in the <param/flags/ parameter. </function> <function><type>void</type> <funcdef>rt_notify</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance <tagp><type>net *</type> <param>net</param></tagp> a network entry <tagp><type>rte *</type> <param>new</param></tagp> new route for the network <tagp><type>rte *</type> <param>old</param></tagp> old route for the network <tagp><type>ea_list *</type> <param>attrs</param></tagp> extended attributes associated with the <param/new/ entry </descrip> <funcsect>Description The <func/rt_notify()/ hook is called to inform the protocol instance about changes in the connected routing table <param/table/, that is a route <param/old/ belonging to network <param/net/ being replaced by a new route <param/new/ with extended attributes <param/attrs/. Either <param/new/ or <param/old/ or both can be <const/NULL/ if the corresponding route doesn't exist. If the type of route announcement is RA_OPTIMAL, it is an announcement of optimal route change, <param/new/ stores the new optimal route and <param/old/ stores the old optimal route. If the type of route announcement is RA_ANY, it is an announcement of any route change, <param/new/ stores the new route and <param/old/ stores the old route from the same protocol. <param/p/->accept_ra_types specifies which kind of route announcements protocol wants to receive. </function> <function><type>void</type> <funcdef>neigh_notify</funcdef> (<type>neighbor *</type> <param>neigh</param>) -- notify instance about neighbor status change <funcsect>Arguments <descrip> <tagp><type>neighbor *</type> <param>neigh</param></tagp> a neighbor cache entry </descrip> <funcsect>Description The <func/neigh_notify()/ hook is called by the neighbor cache whenever a neighbor changes its state, that is it gets disconnected or a sticky neighbor gets connected. </function> <function><type>ea_list *</type> <funcdef>make_tmp_attrs</funcdef> (<type>rte *</type> <param>e</param>, <type>struct linpool *</type> <param>pool</param>) -- convert embedded attributes to temporary ones <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>e</param></tagp> route entry <tagp><type>struct linpool *</type> <param>pool</param></tagp> linear pool to allocate attribute memory in </descrip> <funcsect>Description This hook is called by the routing table functions if they need to convert the protocol attributes embedded directly in the <struct/rte/ to temporary extended attributes in order to distribute them to other protocols or to filters. <func/make_tmp_attrs()/ creates an <struct/ea_list/ in the linear pool <param/pool/, fills it with values of the temporary attributes and returns a pointer to it. </function> <function><type>void</type> <funcdef>store_tmp_attrs</funcdef> (<type>rte *</type> <param>e</param>, <type>ea_list *</type> <param>attrs</param>) -- convert temporary attributes to embedded ones <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>e</param></tagp> route entry <tagp><type>ea_list *</type> <param>attrs</param></tagp> temporary attributes to be converted </descrip> <funcsect>Description This hook is an exact opposite of <func/make_tmp_attrs()/ -- it takes a list of extended attributes and converts them to attributes embedded in the <struct/rte/ corresponding to this protocol. You must be prepared for any of the attributes being missing from the list and use default values instead. </function> <function><type>int</type> <funcdef>import_control</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol instance the route is going to be imported to <tagp><type>rte **</type> <param>e</param></tagp> the route in question <tagp><type>ea_list **</type> <param>attrs</param></tagp> extended attributes of the route <tagp><type>struct linpool *</type> <param>pool</param></tagp> linear pool for allocation of all temporary data </descrip> <funcsect>Description The <func/import_control()/ hook is called as the first step of a exporting a route from a routing table to the protocol instance. It can modify route attributes and force acceptance or rejection of the route regardless of user-specified filters. See <func/rte_announce()/ for a complete description of the route distribution process. The standard use of this hook is to reject routes having originated from the same instance and to set default values of the protocol's metrics. <funcsect>Result 1 if the route has to be accepted, -1 if rejected and 0 if it should be passed to the filters. </function> <function><type>int</type> <funcdef>rte_recalculate</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct rtable *</type> <param>table</param></tagp> a routing table <tagp><type>struct network *</type> <param>net</param></tagp> a network entry <tagp><type>struct rte *</type> <param>new</param></tagp> new route for the network <tagp><type>struct rte *</type> <param>old</param></tagp> old route for the network <tagp><type>struct rte *</type> <param>old_best</param></tagp> old best route for the network (may be NULL) </descrip> <funcsect>Description This hook is called when a route change (from <param/old/ to <param/new/ for a <param/net/ entry) is propagated to a <param/table/. It may be used to prepare routes for comparison by <func/rte_better()/ in the best route selection. <param/new/ may or may not be in <param/net/->routes list, <param/old/ is not there. <funcsect>Result 1 if the ordering implied by <func/rte_better()/ changes enough that full best route calculation have to be done, 0 otherwise. </function> <function><type>int</type> <funcdef>rte_better</funcdef> (<type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>) -- compare metrics of two routes <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>new</param></tagp> the new route <tagp><type>rte *</type> <param>old</param></tagp> the original route </descrip> <funcsect>Description This hook gets called when the routing table contains two routes for the same network which have originated from different instances of a single protocol and it wants to select which one is preferred over the other one. Protocols usually decide according to route metrics. <funcsect>Result 1 if <param/new/ is better (more preferred) than <param/old/, 0 otherwise. </function> <function><type>int</type> <funcdef>rte_same</funcdef> (<type>rte *</type> <param>e1</param>, <type>rte *</type> <param>e2</param>) -- compare two routes <funcsect>Arguments <descrip> <tagp><type>rte *</type> <param>e1</param></tagp> route <tagp><type>rte *</type> <param>e2</param></tagp> route </descrip> <funcsect>Description The <func/rte_same()/ hook tests whether the routes <param/e1/ and <param/e2/ belonging to the same protocol instance have identical contents. Contents of <struct/rta/, all the extended attributes and <struct/rte/ preference are checked by the core code, no need to take care of them here. <funcsect>Result 1 if <param/e1/ is identical to <param/e2/, 0 otherwise. </function> <function><type>void</type> <funcdef>rte_insert</funcdef> (<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>) -- notify instance about route insertion <funcsect>Arguments <descrip> <tagp><type>net *</type> <param>n</param></tagp> network <tagp><type>rte *</type> <param>e</param></tagp> route </descrip> <funcsect>Description This hook is called whenever a <struct/rte/ belonging to the instance is accepted for insertion to a routing table. Please avoid using this function in new protocols. </function> <function><type>void</type> <funcdef>rte_remove</funcdef> (<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>) -- notify instance about route removal <funcsect>Arguments <descrip> <tagp><type>net *</type> <param>n</param></tagp> network <tagp><type>rte *</type> <param>e</param></tagp> route </descrip> <funcsect>Description This hook is called whenever a <struct/rte/ belonging to the instance is removed from a routing table. Please avoid using this function in new protocols. </function> <sect>Interfaces The interface module keeps track of all network interfaces in the system and their addresses. Each interface is represented by an <struct/iface/ structure which carries interface capability flags (<const/IF_MULTIACCESS/, <const/IF_BROADCAST/ etc.), MTU, interface name and index and finally a linked list of network prefixes assigned to the interface, each one represented by struct <struct/ifa/. The interface module keeps a `soft-up' state for each <struct/iface/ which is a conjunction of link being up, the interface being of a `sane' type and at least one IP address assigned to it. <function><type>void</type> <funcdef>ifa_dump</funcdef> (<type>struct ifa *</type> <param>a</param>) -- dump interface address <funcsect>Arguments <descrip> <tagp><type>struct ifa *</type> <param>a</param></tagp> interface address descriptor </descrip> <funcsect>Description This function dumps contents of an <struct/ifa/ to the debug output. </function> <function><type>void</type> <funcdef>if_dump</funcdef> (<type>struct iface *</type> <param>i</param>) -- dump interface <funcsect>Arguments <descrip> <tagp><type>struct iface *</type> <param>i</param></tagp> interface to dump </descrip> <funcsect>Description This function dumps all information associated with a given network interface to the debug output. </function> <function><type>void</type> <funcdef>if_dump_all</funcdef> (<param>void</param>) -- dump all interfaces <funcsect>Description This function dumps information about all known network interfaces to the debug output. </function> <function><type>void</type> <funcdef>if_delete</funcdef> (<type>struct iface *</type> <param>old</param>) -- remove interface <funcsect>Arguments <descrip> <tagp><type>struct iface *</type> <param>old</param></tagp> interface </descrip> <funcsect>Description This function is called by the low-level platform dependent code whenever it notices an interface disappears. It is just a shorthand for <func/if_update()/. </function> <function><type>struct iface *</type> <funcdef>if_update</funcdef> (<type>struct iface *</type> <param>new</param>) -- update interface status <funcsect>Arguments <descrip> <tagp><type>struct iface *</type> <param>new</param></tagp> new interface status </descrip> <funcsect>Description <func/if_update()/ is called by the low-level platform dependent code whenever it notices an interface change. There exist two types of interface updates -- synchronous and asynchronous ones. In the synchronous case, the low-level code calls <func/if_start_update()/, scans all interfaces reported by the OS, uses <func/if_update()/ and <func/ifa_update()/ to pass them to the core and then it finishes the update sequence by calling <func/if_end_update()/. When working asynchronously, the sysdep code calls <func/if_update()/ and <func/ifa_update()/ whenever it notices a change. <func/if_update()/ will automatically notify all other modules about the change. </function> <function><type>void</type> <funcdef>if_feed_baby</funcdef> (<type>struct proto *</type> <param>p</param>) -- advertise interfaces to a new protocol <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol to feed </descrip> <funcsect>Description When a new protocol starts, this function sends it a series of notifications about all existing interfaces. </function> <function><type>struct iface *</type> <funcdef>if_find_by_index</funcdef> (<type>unsigned</type> <param>idx</param>) -- find interface by ifindex <funcsect>Arguments <descrip> <tagp><type>unsigned</type> <param>idx</param></tagp> ifindex </descrip> <funcsect>Description This function finds an <struct/iface/ structure corresponding to an interface of the given index <param/idx/. Returns a pointer to the structure or <const/NULL/ if no such structure exists. </function> <function><type>struct iface *</type> <funcdef>if_find_by_name</funcdef> (<type>char *</type> <param>name</param>) -- find interface by name <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>name</param></tagp> interface name </descrip> <funcsect>Description This function finds an <struct/iface/ structure corresponding to an interface of the given name <param/name/. Returns a pointer to the structure or <const/NULL/ if no such structure exists. </function> <function><type>struct ifa *</type> <funcdef>ifa_update</funcdef> (<type>struct ifa *</type> <param>a</param>) -- update interface address <funcsect>Arguments <descrip> <tagp><type>struct ifa *</type> <param>a</param></tagp> new interface address </descrip> <funcsect>Description This function adds address information to a network interface. It's called by the platform dependent code during the interface update process described under <func/if_update()/. </function> <function><type>void</type> <funcdef>ifa_delete</funcdef> (<type>struct ifa *</type> <param>a</param>) -- remove interface address <funcsect>Arguments <descrip> <tagp><type>struct ifa *</type> <param>a</param></tagp> interface address </descrip> <funcsect>Description This function removes address information from a network interface. It's called by the platform dependent code during the interface update process described under <func/if_update()/. </function> <function><type>void</type> <funcdef>if_init</funcdef> (<param>void</param>) -- initialize interface module <funcsect>Description This function is called during BIRD startup to initialize all data structures of the interface module. </function> <sect>Neighbor cache Most routing protocols need to associate their internal state data with neighboring routers, check whether an address given as the next hop attribute of a route is really an address of a directly connected host and which interface is it connected through. Also, they often need to be notified when a neighbor ceases to exist or when their long awaited neighbor becomes connected. The neighbor cache is there to solve all these problems. The neighbor cache maintains a collection of neighbor entries. Each entry represents one IP address corresponding to either our directly connected neighbor or our own end of the link (when the scope of the address is set to <const/SCOPE_HOST/) together with per-neighbor data belonging to a single protocol. Active entries represent known neighbors and are stored in a hash table (to allow fast retrieval based on the IP address of the node) and two linked lists: one global and one per-interface (allowing quick processing of interface change events). Inactive entries exist only when the protocol has explicitly requested it via the <const/NEF_STICKY/ flag because it wishes to be notified when the node will again become a neighbor. Such entries are enqueued in a special list which is walked whenever an interface changes its state to up. Neighbor entry VRF association is implied by respective protocol. When a neighbor event occurs (a neighbor gets disconnected or a sticky inactive neighbor becomes connected), the protocol hook <func/neigh_notify()/ is called to advertise the change. <function><type>neighbor *</type> <funcdef>neigh_find</funcdef> (<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. <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>p</param></tagp> protocol which asks for the entry. <tagp><type>ip_addr *</type> <param>a</param></tagp> pointer to IP address of the node to be searched for. <tagp><type>unsigned</type> <param>flags</param></tagp> 0 or <const/NEF_STICKY/ if you want to create a sticky entry. </descrip> <funcsect>Description Search the neighbor cache for a node with given IP address. If it's found, a pointer to the neighbor entry is returned. If no such entry exists and the node is directly connected on one of our active interfaces, a new entry is created and returned to the caller with protocol-dependent fields initialized to zero. If the node is not connected directly or *<param/a/ is not a valid unicast IP address, <func/neigh_find()/ returns <const/NULL/. </function> <function><type>void</type> <funcdef>neigh_dump</funcdef> (<type>neighbor *</type> <param>n</param>) -- dump specified neighbor entry. <funcsect>Arguments <descrip> <tagp><type>neighbor *</type> <param>n</param></tagp> the entry to dump </descrip> <funcsect>Description This functions dumps the contents of a given neighbor entry to debug output. </function> <function><type>void</type> <funcdef>neigh_dump_all</funcdef> (<param>void</param>) -- dump all neighbor entries. <funcsect>Description This function dumps the contents of the neighbor cache to debug output. </function> <function><type>void</type> <funcdef>neigh_if_up</funcdef> (<type>struct iface *</type> <param>i</param>) <funcsect>Arguments <descrip> <tagp><type>struct iface *</type> <param>i</param></tagp> interface in question </descrip> <funcsect>Description Tell the neighbor cache that a new interface became up. The neighbor cache wakes up all inactive sticky neighbors with addresses belonging to prefixes of the interface <param/i/. </function> <function><type>void</type> <funcdef>neigh_if_down</funcdef> (<type>struct iface *</type> <param>i</param>) -- notify neighbor cache about interface down event <funcsect>Arguments <descrip> <tagp><type>struct iface *</type> <param>i</param></tagp> the interface in question </descrip> <funcsect>Description Notify the neighbor cache that an interface has ceased to exist. It causes all entries belonging to neighbors connected to this interface to be flushed. </function> <function><type>void</type> <funcdef>neigh_if_link</funcdef> (<type>struct iface *</type> <param>i</param>) -- notify neighbor cache about interface link change <funcsect>Arguments <descrip> <tagp><type>struct iface *</type> <param>i</param></tagp> the interface in question </descrip> <funcsect>Description Notify the neighbor cache that an interface changed link state. All owners of neighbor entries connected to this interface are notified. </function> <function><type>void</type> <funcdef>neigh_ifa_update</funcdef> (<type>struct ifa *</type> <param>a</param>) <funcsect>Arguments <descrip> <tagp><type>struct ifa *</type> <param>a</param></tagp> interface address in question </descrip> <funcsect>Description Tell the neighbor cache that an address was added or removed. The neighbor cache wakes up all inactive sticky neighbors with addresses belonging to prefixes of the interface belonging to <param/ifa/ and causes all unreachable neighbors to be flushed. </function> <function><type>void</type> <funcdef>neigh_prune</funcdef> (<param>void</param>) -- prune neighbor cache <funcsect>Description <func/neigh_prune()/ examines all neighbor entries cached and removes those corresponding to inactive protocols. It's called whenever a protocol is shut down to get rid of all its heritage. </function> <function><type>void</type> <funcdef>neigh_init</funcdef> (<type>pool *</type> <param>if_pool</param>) -- initialize the neighbor cache. <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>if_pool</param></tagp> resource pool to be used for neighbor entries. </descrip> <funcsect>Description This function is called during BIRD startup to initialize the neighbor cache module. </function> <sect>Command line interface This module takes care of the BIRD's command-line interface (CLI). The CLI exists to provide a way to control BIRD remotely and to inspect its status. It uses a very simple textual protocol over a stream connection provided by the platform dependent code (on UNIX systems, it's a UNIX domain socket). Each session of the CLI consists of a sequence of request and replies, slightly resembling the FTP and SMTP protocols. Requests are commands encoded as a single line of text, replies are sequences of lines starting with a four-digit code followed by either a space (if it's the last line of the reply) or a minus sign (when the reply is going to continue with the next line), the rest of the line contains a textual message semantics of which depends on the numeric code. If a reply line has the same code as the previous one and it's a continuation line, the whole prefix can be replaced by a single white space character. Reply codes starting with 0 stand for `action successfully completed' messages, 1 means `table entry', 8 `runtime error' and 9 `syntax error'. Each CLI session is internally represented by a <struct/cli/ structure and a resource pool containing all resources associated with the connection, so that it can be easily freed whenever the connection gets closed, not depending on the current state of command processing. The CLI commands are declared as a part of the configuration grammar by using the <tt>CF_CLI</tt> macro. When a command is received, it is processed by the same lexical analyzer and parser as used for the configuration, but it's switched to a special mode by prepending a fake token to the text, so that it uses only the CLI command rules. Then the parser invokes an execution routine corresponding to the command, which either constructs the whole reply and returns it back or (in case it expects the reply will be long) it prints a partial reply and asks the CLI module (using the <param/cont/ hook) to call it again when the output is transferred to the user. The <param/this_cli/ variable points to a <struct/cli/ structure of the session being currently parsed, but it's of course available only in command handlers not entered using the <param/cont/ hook. TX buffer management works as follows: At cli.tx_buf there is a list of TX buffers (struct cli_out), cli.tx_write is the buffer currently used by the producer (<func/cli_printf()/, <func/cli_alloc_out()/) and cli.tx_pos is the buffer currently used by the consumer (<func/cli_write()/, in system dependent code). The producer uses cli_out.wpos ptr as the current write position and the consumer uses cli_out.outpos ptr as the current read position. When the producer produces something, it calls <func/cli_write_trigger()/. If there is not enough space in the current buffer, the producer allocates the new one. When the consumer processes everything in the buffer queue, it calls <func/cli_written()/, tha frees all buffers (except the first one) and schedules cli.event . <function><type>void</type> <funcdef>cli_printf</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>cli *</type> <param>c</param></tagp> CLI connection <tagp><type>int</type> <param>code</param></tagp> numeric code of the reply, negative for continuation lines <tagp><type>char *</type> <param>msg</param></tagp> a <func/printf()/-like formatting string. <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function send a single line of reply to a given CLI connection. In works in all aspects like <func/bsprintf()/ except that it automatically prepends the reply line prefix. Please note that if the connection can be already busy sending some data in which case <func/cli_printf()/ stores the output to a temporary buffer, so please avoid sending a large batch of replies without waiting for the buffers to be flushed. If you want to write to the current CLI output, you can use the <func/cli_msg()/ macro instead. </function> <function><type>void</type> <funcdef>cli_init</funcdef> (<param>void</param>) -- initialize the CLI module <funcsect>Description This function is called during BIRD startup to initialize the internal data structures of the CLI module. </function> <sect>Object locks The lock module provides a simple mechanism for avoiding conflicts between various protocols which would like to use a single physical resource (for example a network port). It would be easy to say that such collisions can occur only when the user specifies an invalid configuration and therefore he deserves to get what he has asked for, but unfortunately they can also arise legitimately when the daemon is reconfigured and there exists (although for a short time period only) an old protocol instance being shut down and a new one willing to start up on the same interface. The solution is very simple: when any protocol wishes to use a network port or some other non-shareable resource, it asks the core to lock it and it doesn't use the resource until it's notified that it has acquired the lock. Object locks are represented by <struct/object_lock/ structures which are in turn a kind of resource. Lockable resources are uniquely determined by resource type (<const/OBJLOCK_UDP/ for a UDP port etc.), IP address (usually a broadcast or multicast address the port is bound to), port number, interface and optional instance ID. <function><type>struct object_lock *</type> <funcdef>olock_new</funcdef> (<type>pool *</type> <param>p</param>) -- create an object lock <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> resource pool to create the lock in. </descrip> <funcsect>Description The <func/olock_new()/ function creates a new resource of type <struct/object_lock/ and returns a pointer to it. After filling in the structure, the caller should call <func/olock_acquire()/ to do the real locking. </function> <function><type>void</type> <funcdef>olock_acquire</funcdef> (<type>struct object_lock *</type> <param>l</param>) -- acquire a lock <funcsect>Arguments <descrip> <tagp><type>struct object_lock *</type> <param>l</param></tagp> the lock to acquire </descrip> <funcsect>Description This function attempts to acquire exclusive access to the non-shareable resource described by the lock <param/l/. It returns immediately, but as soon as the resource becomes available, it calls the <func/hook()/ function set up by the caller. When you want to release the resource, just <func/rfree()/ the lock. </function> <function><type>void</type> <funcdef>olock_init</funcdef> (<param>void</param>) -- initialize the object lock mechanism <funcsect>Description This function is called during BIRD startup. It initializes all the internal data structures of the lock module. </function> <chapt>Configuration <sect>Configuration manager Configuration of BIRD is complex, yet straightforward. There are three modules taking care of the configuration: config manager (which takes care of storage of the config information and controls switching between configs), lexical analyzer and parser. The configuration manager stores each config as a <struct/config/ structure accompanied by a linear pool from which all information associated with the config and pointed to by the <struct/config/ structure is allocated. There can exist up to four different configurations at one time: an active one (pointed to by <param/config/), configuration we are just switching from (<param/old_config/), one queued for the next reconfiguration (<param/future_config/; if there is one and the user wants to reconfigure once again, we just free the previous queued config and replace it with the new one) and finally a config being parsed (<param/new_config/). The stored <param/old_config/ is also used for undo reconfiguration, which works in a similar way. Reconfiguration could also have timeout (using <param/config_timer/) and undo is automatically called if the new configuration is not confirmed later. The new config (<param/new_config/) and associated linear pool (<param/cfg_mem/) is non-NULL only during parsing. Loading of new configuration is very simple: just call <func/config_alloc()/ to get a new <struct/config/ structure, then use <func/config_parse()/ to parse a configuration file and fill all fields of the structure and finally ask the config manager to switch to the new config by calling <func/config_commit()/. CLI commands are parsed in a very similar way -- there is also a stripped-down <struct/config/ structure associated with them and they are lex-ed and parsed by the same functions, only a special fake token is prepended before the command text to make the parser recognize only the rules corresponding to CLI commands. <function><type>struct config *</type> <funcdef>config_alloc</funcdef> (<type>const byte *</type> <param>name</param>) -- allocate a new configuration <funcsect>Arguments <descrip> <tagp><type>const byte *</type> <param>name</param></tagp> name of the config </descrip> <funcsect>Description This function creates new <struct/config/ structure, attaches a resource pool and a linear memory pool to it and makes it available for further use. Returns a pointer to the structure. </function> <function><type>int</type> <funcdef>config_parse</funcdef> (<type>struct config *</type> <param>c</param>) -- parse a configuration <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>c</param></tagp> configuration </descrip> <funcsect>Description <func/config_parse()/ reads input by calling a hook function pointed to by <param/cf_read_hook/ and parses it according to the configuration grammar. It also calls all the preconfig and postconfig hooks before, resp. after parsing. <funcsect>Result 1 if the config has been parsed successfully, 0 if any error has occurred (such as anybody calling <func/cf_error()/) and the <param/err_msg/ field has been set to the error message. </function> <function><type>int</type> <funcdef>cli_parse</funcdef> (<type>struct config *</type> <param>c</param>) -- parse a CLI command <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>c</param></tagp> temporary config structure </descrip> <funcsect>Description <func/cli_parse()/ is similar to <func/config_parse()/, but instead of a configuration, it parses a CLI command. See the CLI module for more information. </function> <function><type>void</type> <funcdef>config_free</funcdef> (<type>struct config *</type> <param>c</param>) -- free a configuration <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>c</param></tagp> configuration to be freed </descrip> <funcsect>Description This function takes a <struct/config/ structure and frees all resources associated with it. </function> <function><type>int</type> <funcdef>config_commit</funcdef> (<type>struct config *</type> <param>c</param>, <type>int</type> <param>type</param>, <type>int</type> <param>timeout</param>) -- commit a configuration <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>c</param></tagp> new configuration <tagp><type>int</type> <param>type</param></tagp> type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD) <tagp><type>int</type> <param>timeout</param></tagp> timeout for undo (or 0 for no timeout) </descrip> <funcsect>Description When a configuration is parsed and prepared for use, the <func/config_commit()/ function starts the process of reconfiguration. It checks whether there is already a reconfiguration in progress in which case it just queues the new config for later processing. Else it notifies all modules about the new configuration by calling their <func/commit()/ functions which can either accept it immediately or call <func/config_add_obstacle()/ to report that they need some time to complete the reconfiguration. After all such obstacles are removed using <func/config_del_obstacle()/, the old configuration is freed and everything runs according to the new one. When <param/timeout/ is nonzero, the undo timer is activated with given timeout. The timer is deactivated when <func/config_commit()/, <func/config_confirm()/ or <func/config_undo()/ is called. <funcsect>Result <const/CONF_DONE/ if the configuration has been accepted immediately, <const/CONF_PROGRESS/ if it will take some time to switch to it, <const/CONF_QUEUED/ if it's been queued due to another reconfiguration being in progress now or <const/CONF_SHUTDOWN/ if BIRD is in shutdown mode and no new configurations are accepted. </function> <function><type>int</type> <funcdef>config_confirm</funcdef> (<param>void</param>) -- confirm a commited configuration <funcsect>Description When the undo timer is activated by <func/config_commit()/ with nonzero timeout, this function can be used to deactivate it and therefore confirm the current configuration. <funcsect>Result <const/CONF_CONFIRM/ when the current configuration is confirmed, <const/CONF_NONE/ when there is nothing to confirm (i.e. undo timer is not active). </function> <function><type>int</type> <funcdef>config_undo</funcdef> (<param>void</param>) -- undo a configuration <funcsect>Description Function <func/config_undo()/ can be used to change the current configuration back to stored <const/old_config/. If no reconfiguration is running, this stored configuration is commited in the same way as a new configuration in <func/config_commit()/. If there is already a reconfiguration in progress and no next reconfiguration is scheduled, then the undo is scheduled for later processing as usual, but if another reconfiguration is already scheduled, then such reconfiguration is removed instead (i.e. undo is applied on the last commit that scheduled it). <funcsect>Result <const/CONF_DONE/ if the configuration has been accepted immediately, <const/CONF_PROGRESS/ if it will take some time to switch to it, <const/CONF_QUEUED/ if it's been queued due to another reconfiguration being in progress now, <const/CONF_UNQUEUED/ if a scheduled reconfiguration is removed, <const/CONF_NOTHING/ if there is no relevant configuration to undo (the previous config request was <func/config_undo()/ too) or <const/CONF_SHUTDOWN/ if BIRD is in shutdown mode and no new configuration changes are accepted. </function> <function><type>void</type> <funcdef>order_shutdown</funcdef> (<param>void</param>) -- order BIRD shutdown <funcsect>Description This function initiates shutdown of BIRD. It's accomplished by asking for switching to an empty configuration. </function> <function><type>void</type> <funcdef>cf_error</funcdef> (<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report a configuration error <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>msg</param></tagp> printf-like format string <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description <func/cf_error()/ can be called during execution of <func/config_parse()/, that is from the parser, a preconfig hook or a postconfig hook, to report an error in the configuration. </function> <function><type>char *</type> <funcdef>cfg_strdup</funcdef> (<type>const char *</type> <param>c</param>) -- copy a string to config memory <funcsect>Arguments <descrip> <tagp><type>const char *</type> <param>c</param></tagp> string to copy </descrip> <funcsect>Description <func/cfg_strdup()/ creates a new copy of the string in the memory pool associated with the configuration being currently parsed. It's often used when a string literal occurs in the configuration and we want to preserve it for further use. </function> <sect>Lexical analyzer The lexical analyzer used for configuration files and CLI commands is generated using the <tt>flex</tt> tool accompanied by a couple of functions maintaining the hash tables containing information about symbols and keywords. Each symbol is represented by a <struct/symbol/ structure containing name of the symbol, its lexical scope, symbol class (<const/SYM_PROTO/ for a name of a protocol, <const/SYM_CONSTANT/ for a constant etc.) and class dependent data. When an unknown symbol is encountered, it's automatically added to the symbol table with class <const/SYM_VOID/. The keyword tables are generated from the grammar templates using the <tt>gen_keywords.m4</tt> script. <function><type>void</type> <funcdef>cf_lex_unwind</funcdef> (<param>void</param>) -- unwind lexer state during error <funcsect>Lexical analyzer <func/cf_lex_unwind()/ frees the internal state on IFS stack when the lexical analyzer is terminated by <func/cf_error()/. </function> <function><type>struct symbol *</type> <funcdef>cf_find_symbol</funcdef> (<type>struct config *</type> <param>cfg</param>, <type>byte *</type> <param>c</param>) -- find a symbol by name <funcsect>Arguments <descrip> <tagp><type>struct config *</type> <param>cfg</param></tagp> specificed config <tagp><type>byte *</type> <param>c</param></tagp> symbol name </descrip> <funcsect>Description This functions searches the symbol table in the config <param/cfg/ for a symbol of given name. First it examines the current scope, then the second recent one and so on until it either finds the symbol and returns a pointer to its <struct/symbol/ structure or reaches the end of the scope chain and returns <const/NULL/ to signify no match. </function> <function><type>struct symbol *</type> <funcdef>cf_get_symbol</funcdef> (<type>byte *</type> <param>c</param>) -- get a symbol by name <funcsect>Arguments <descrip> <tagp><type>byte *</type> <param>c</param></tagp> symbol name </descrip> <funcsect>Description This functions searches the symbol table of the currently parsed config (<param/new_config/) for a symbol of given name. It returns either the already existing symbol or a newly allocated undefined (<const/SYM_VOID/) symbol if no existing symbol is found. </function> <function><type>struct symbol *</type> <funcdef>cf_define_symbol</funcdef> (<type>struct symbol *</type> <param>sym</param>, <type>int</type> <param>type</param>, <type>void *</type> <param>def</param>) -- define meaning of a symbol <funcsect>Arguments <descrip> <tagp><type>struct symbol *</type> <param>sym</param></tagp> symbol to be defined <tagp><type>int</type> <param>type</param></tagp> symbol class to assign <tagp><type>void *</type> <param>def</param></tagp> class dependent data </descrip> <funcsect>Description Defines new meaning of a symbol. If the symbol is an undefined one (<const/SYM_VOID/), it's just re-defined to the new type. If it's defined in different scope, a new symbol in current scope is created and the meaning is assigned to it. If it's already defined in the current scope, an error is reported via <func/cf_error()/. <funcsect>Result Pointer to the newly defined symbol. If we are in the top-level scope, it's the same <param/sym/ as passed to the function. </function> <function><type>void</type> <funcdef>cf_lex_init</funcdef> (<type>int</type> <param>is_cli</param>, <type>struct config *</type> <param>c</param>) -- initialize the lexer <funcsect>Arguments <descrip> <tagp><type>int</type> <param>is_cli</param></tagp> true if we're going to parse CLI command, false for configuration <tagp><type>struct config *</type> <param>c</param></tagp> configuration structure </descrip> <funcsect>Description <func/cf_lex_init()/ initializes the lexical analyzer and prepares it for parsing of a new input. </function> <function><type>void</type> <funcdef>cf_push_scope</funcdef> (<type>struct symbol *</type> <param>sym</param>) -- enter new scope <funcsect>Arguments <descrip> <tagp><type>struct symbol *</type> <param>sym</param></tagp> symbol representing scope name </descrip> <funcsect>Description If we want to enter a new scope to process declarations inside a nested block, we can just call <func/cf_push_scope()/ to push a new scope onto the scope stack which will cause all new symbols to be defined in this scope and all existing symbols to be sought for in all scopes stored on the stack. </function> <function><type>void</type> <funcdef>cf_pop_scope</funcdef> (<param>void</param>) -- leave a scope <funcsect>Description <func/cf_pop_scope()/ pops the topmost scope from the scope stack, leaving all its symbols in the symbol table, but making them invisible to the rest of the config. </function> <function><type>char *</type> <funcdef>cf_symbol_class_name</funcdef> (<type>struct symbol *</type> <param>sym</param>) -- get name of a symbol class <funcsect>Arguments <descrip> <tagp><type>struct symbol *</type> <param>sym</param></tagp> symbol </descrip> <funcsect>Description This function returns a string representing the class of the given symbol. </function> <sect>Parser Both the configuration and CLI commands are analyzed using a syntax driven parser generated by the <tt>bison</tt> tool from a grammar which is constructed from information gathered from grammar snippets by the <tt>gen_parser.m4</tt> script. Grammar snippets are files (usually with extension <tt>.Y</tt>) contributed by various BIRD modules in order to provide information about syntax of their configuration and their CLI commands. Each snipped consists of several sections, each of them starting with a special keyword: <tt>CF_HDR</tt> for a list of <tt>#include</tt> directives needed by the C code, <tt>CF_DEFINES</tt> for a list of C declarations, <tt>CF_DECLS</tt> for <tt>bison</tt> declarations including keyword definitions specified as <tt>CF_KEYWORDS</tt>, <tt>CF_GRAMMAR</tt> for the grammar rules, <tt>CF_CODE</tt> for auxiliary C code and finally <tt>CF_END</tt> at the end of the snippet. To create references between the snippets, it's possible to define multi-part rules by utilizing the <tt>CF_ADDTO</tt> macro which adds a new alternative to a multi-part rule. CLI commands are defined using a <tt>CF_CLI</tt> macro. Its parameters are: the list of keywords determining the command, the list of parameters, help text for the parameters and help text for the command. Values of <tt>enum</tt> filter types can be defined using <tt>CF_ENUM</tt> with the following parameters: name of filter type, prefix common for all literals of this type and names of all the possible values. <chapt>Filters <sect>Filters You can find sources of the filter language in <tt>filter/</tt> directory. File <tt>filter/config.Y</tt> contains filter grammar and basically translates the source from user into a tree of <struct/f_inst/ structures. These trees are later interpreted using code in <tt>filter/filter.c</tt>. A filter is represented by a tree of <struct/f_inst/ structures, one structure per "instruction". Each <struct/f_inst/ contains <param/code/, <param/aux/ value which is usually the data type this instruction operates on and two generic arguments (<param/a1/, <param/a2/). Some instructions contain pointer(s) to other instructions in their (<param/a1/, <param/a2/) fields. Filters use a <struct/f_val/ structure for their data. Each <struct/f_val/ contains type and value (types are constants prefixed with <const/T_/). Few of the types are special; <const/T_RETURN/ can be or-ed with a type to indicate that return from a function or from the whole filter should be forced. Important thing about <struct/f_val/'s is that they may be copied with a simple <tt>=</tt>. That's fine for all currently defined types: strings are read-only (and therefore okay), paths are copied for each operation (okay too). <function><type>int</type> <funcdef>val_compare</funcdef> (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- compare two values <funcsect>Arguments <descrip> <tagp><type>struct f_val</type> <param>v1</param></tagp> first value <tagp><type>struct f_val</type> <param>v2</param></tagp> second value </descrip> <funcsect>Description Compares two values and returns -1, 0, 1 on <, =, > or CMP_ERROR on error. Tree module relies on this giving consistent results so that it can be used for building balanced trees. </function> <function><type>int</type> <funcdef>val_same</funcdef> (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- compare two values <funcsect>Arguments <descrip> <tagp><type>struct f_val</type> <param>v1</param></tagp> first value <tagp><type>struct f_val</type> <param>v2</param></tagp> second value </descrip> <funcsect>Description Compares two values and returns 1 if they are same and 0 if not. Comparison of values of different types is valid and returns 0. </function> <function><type>int</type> <funcdef>val_in_range</funcdef> (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- implement <tt>~</tt> operator <funcsect>Arguments <descrip> <tagp><type>struct f_val</type> <param>v1</param></tagp> element <tagp><type>struct f_val</type> <param>v2</param></tagp> set </descrip> <funcsect>Description Checks if <param/v1/ is element (<tt>~</tt> operator) of <param/v2/. </function> <function><type>struct f_val</type> <funcdef>interpret</funcdef> (<type>struct f_inst *</type> <param>what</param>) <funcsect>Arguments <descrip> <tagp><type>struct f_inst *</type> <param>what</param></tagp> filter to interpret </descrip> <funcsect>Description Interpret given tree of filter instructions. This is core function of filter system and does all the hard work. <funcsect>Each instruction has 4 fields code (which is instruction code), aux (which is extension to instruction code, typically type), arg1 and arg2 - arguments. Depending on instruction, arguments are either integers, or pointers to instruction trees. Common instructions like +, that have two expressions as arguments use TWOARGS macro to get both of them evaluated. <struct/f_val/ structures are copied around, so there are no problems with memory managment. </function> <function><type>int</type> <funcdef>f_run</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct filter *</type> <param>filter</param></tagp> filter to run <tagp><type>struct rte **</type> <param>rte</param></tagp> route being filtered, may be modified <tagp><type>struct ea_list **</type> <param>tmp_attrs</param></tagp> temporary attributes, prepared by caller or generated by <func/f_run()/ <tagp><type>struct linpool *</type> <param>tmp_pool</param></tagp> all filter allocations go from this pool <tagp><type>int</type> <param>flags</param></tagp> flags </descrip> <funcsect>Description If filter needs to modify the route, there are several posibilities. <param/rte/ might be read-only (with REF_COW flag), in that case rw copy is obtained by <func/rte_cow()/ and <param/rte/ is replaced. If <param/rte/ is originally rw, it may be directly modified (and it is never copied). The returned rte may reuse the (possibly cached, cloned) rta, or (if rta was modificied) contains a modified uncached rta, which uses parts allocated from <param/tmp_pool/ and parts shared from original rta. There is one exception - if <param/rte/ is rw but contains a cached rta and that is modified, rta in returned rte is also cached. Ownership of cached rtas is consistent with rte, i.e. if a new rte is returned, it has its own clone of cached rta (and cached rta of read-only source rte is intact), if rte is modified in place, old cached rta is possibly freed. </function> <function><type>int</type> <funcdef>filter_same</funcdef> (<type>struct filter *</type> <param>new</param>, <type>struct filter *</type> <param>old</param>) -- compare two filters <funcsect>Arguments <descrip> <tagp><type>struct filter *</type> <param>new</param></tagp> first filter to be compared <tagp><type>struct filter *</type> <param>old</param></tagp> second filter to be compared, notice that this filter is damaged while comparing. </descrip> <funcsect>Description Returns 1 in case filters are same, otherwise 0. If there are underlying bugs, it will rather say 0 on same filters than say 1 on different. </function> <function><type>struct f_tree *</type> <funcdef>find_tree</funcdef> (<type>struct f_tree *</type> <param>t</param>, <type>struct f_val</type> <param>val</param>) <funcsect>Arguments <descrip> <tagp><type>struct f_tree *</type> <param>t</param></tagp> tree to search in <tagp><type>struct f_val</type> <param>val</param></tagp> value to find </descrip> <funcsect>Description Search for given value in the tree. I relies on fact that sorted tree is populated by <struct/f_val/ structures (that can be compared by <func/val_compare()/). In each node of tree, either single value (then t->from==t->to) or range is present. Both set matching and <tt><func/switch()/ { }</tt> construction is implemented using this function, thus both are as fast as they can be. </function> <function><type>struct f_tree *</type> <funcdef>build_tree</funcdef> (<type>struct f_tree *</type> <param>from</param>) <funcsect>Arguments <descrip> <tagp><type>struct f_tree *</type> <param>from</param></tagp> degenerated tree (linked by <param/tree/->left) to be transformed into form suitable for <func/find_tree()/ </descrip> <funcsect>Description Transforms degenerated tree into balanced tree. </function> <function><type>int</type> <funcdef>same_tree</funcdef> (<type>struct f_tree *</type> <param>t1</param>, <type>struct f_tree *</type> <param>t2</param>) <funcsect>Arguments <descrip> <tagp><type>struct f_tree *</type> <param>t1</param></tagp> first tree to be compared <tagp><type>struct f_tree *</type> <param>t2</param></tagp> second one </descrip> <funcsect>Description Compares two trees and returns 1 if they are same </function> <sect>Trie for prefix sets We use a (compressed) trie to represent prefix sets. Every node in the trie represents one prefix (<struct/addr//<struct/plen/) and <struct/plen/ also indicates the index of the bit in the address that is used to branch at the node. If we need to represent just a set of prefixes, it would be simple, but we have to represent a set of prefix patterns. Each prefix pattern consists of <struct/ppaddr//<struct/pplen/ and two integers: <struct/low/ and <struct/high/, and a prefix <struct/paddr//<struct/plen/ matches that pattern if the first MIN(<struct/plen/, <struct/pplen/) bits of <struct/paddr/ and <struct/ppaddr/ are the same and <struct/low/ <= <struct/plen/ <= <struct/high/. We use a bitmask (<struct/accept/) to represent accepted prefix lengths at a node. As there are 33 prefix lengths (0..32 for IPv4), but there is just one prefix of zero length in the whole trie so we have <struct/zero/ flag in <struct/f_trie/ (indicating whether the trie accepts prefix 0.0.0.0/0) as a special case, and <struct/accept/ bitmask represents accepted prefix lengths from 1 to 32. There are two cases in prefix matching - a match when the length of the prefix is smaller that the length of the prefix pattern, (<struct/plen/ < <struct/pplen/) and otherwise. The second case is simple - we just walk through the trie and look at every visited node whether that prefix accepts our prefix length (<struct/plen/). The first case is tricky - we don't want to examine every descendant of a final node, so (when we create the trie) we have to propagate that information from nodes to their ascendants. Suppose that we have two masks (M1 and M2) for a node. Mask M1 represents accepted prefix lengths by just the node and mask M2 represents accepted prefix lengths by the node or any of its descendants. Therefore M2 is a bitwise or of M1 and children's M2 and this is a maintained invariant during trie building. Basically, when we want to match a prefix, we walk through the trie, check mask M1 for our prefix length and when we came to final node, we check mask M2. There are two differences in the real implementation. First, we use a compressed trie so there is a case that we skip our final node (if it is not in the trie) and we came to node that is either extension of our prefix, or completely out of path In the first case, we also have to check M2. Second, we really need not to maintain two separate bitmasks. Checks for mask M1 are always larger than <struct/applen/ and we need just the first <struct/pplen/ bits of mask M2 (if trie compression hadn't been used it would suffice to know just $applen-th bit), so we have to store them together in <struct/accept/ mask - the first <struct/pplen/ bits of mask M2 and then mask M1. There are four cases when we walk through a trie: - we are in NULL - we are out of path (prefixes are inconsistent) - we are in the wanted (final) node (node length == <struct/plen/) - we are beyond the end of path (node length > <struct/plen/) - we are still on path and keep walking (node length < <struct/plen/) The walking code in <func/trie_match_prefix()/ is structured according to these cases. <function><type>struct f_trie *</type> <funcdef>f_new_trie</funcdef> (<type>linpool *</type> <param>lp</param>, <type>uint</type> <param>node_size</param>) -- allocates and returns a new empty trie <funcsect>Arguments <descrip> <tagp><type>linpool *</type> <param>lp</param></tagp> linear pool to allocate items from <tagp><type>uint</type> <param>node_size</param></tagp> node size to be used (<struct/f_trie_node/ and user data) </descrip> </function> <function><type>void *</type> <funcdef>trie_add_prefix</funcdef> (<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>) <funcsect>Arguments <descrip> <tagp><type>struct f_trie *</type> <param>t</param></tagp> trie to add to <tagp><type>ip_addr</type> <param>px</param></tagp> prefix address <tagp><type>int</type> <param>plen</param></tagp> prefix length <tagp><type>int</type> <param>l</param></tagp> prefix lower bound <tagp><type>int</type> <param>h</param></tagp> prefix upper bound </descrip> <funcsect>Description Adds prefix (prefix pattern) <param/px//<param/plen/ to trie <param/t/. <param/l/ and <param/h/ are lower and upper bounds on accepted prefix lengths, both inclusive. 0 <= l, h <= 32 (128 for IPv6). Returns a pointer to the allocated node. The function can return a pointer to an existing node if <param/px/ and <param/plen/ are the same. If px/plen == 0/0 (or ::/0), a pointer to the root node is returned. </function> <function><type>int</type> <funcdef>trie_match_prefix</funcdef> (<type>struct f_trie *</type> <param>t</param>, <type>ip_addr</type> <param>px</param>, <type>int</type> <param>plen</param>) <funcsect>Arguments <descrip> <tagp><type>struct f_trie *</type> <param>t</param></tagp> trie <tagp><type>ip_addr</type> <param>px</param></tagp> prefix address <tagp><type>int</type> <param>plen</param></tagp> prefix length </descrip> <funcsect>Description Tries to find a matching prefix pattern in the trie such that prefix <param/px//<param/plen/ matches that prefix pattern. Returns 1 if there is such prefix pattern in the trie. </function> <function><type>int</type> <funcdef>trie_same</funcdef> (<type>struct f_trie *</type> <param>t1</param>, <type>struct f_trie *</type> <param>t2</param>) <funcsect>Arguments <descrip> <tagp><type>struct f_trie *</type> <param>t1</param></tagp> first trie to be compared <tagp><type>struct f_trie *</type> <param>t2</param></tagp> second one </descrip> <funcsect>Description Compares two tries and returns 1 if they are same </function> <function><type>void</type> <funcdef>trie_format</funcdef> (<type>struct f_trie *</type> <param>t</param>, <type>buffer *</type> <param>buf</param>) <funcsect>Arguments <descrip> <tagp><type>struct f_trie *</type> <param>t</param></tagp> trie to be formatted <tagp><type>buffer *</type> <param>buf</param></tagp> destination buffer </descrip> <funcsect>Description Prints the trie to the supplied buffer. </function> <chapt>Protocols <sect>The Babel protocol Babel (RFC6126) is a loop-avoiding distance-vector routing protocol that is robust and efficient both in ordinary wired networks and in wireless mesh networks. The Babel protocol keeps state for each neighbour in a <struct/babel_neighbor/ struct, tracking received Hello and I Heard You (IHU) messages. A <struct/babel_interface/ struct keeps hello and update times for each interface, and a separate hello seqno is maintained for each interface. For each prefix, Babel keeps track of both the possible routes (with next hop and router IDs), as well as the feasibility distance for each prefix and router id. The prefix itself is tracked in a <struct/babel_entry/ struct, while the possible routes for the prefix are tracked as <struct/babel_route/ entries and the feasibility distance is maintained through <struct/babel_source/ structures. The main route selection is done in <func/babel_select_route()/. This is called when an entry is updated by receiving updates from the network or when modified by internal timers. It performs feasibility checks on the available routes for the prefix and selects the one with the lowest metric to be announced to the core. <function><type>void</type> <funcdef>babel_announce_rte</funcdef> (<type>struct babel_proto *</type> <param>p</param>, <type>struct babel_entry *</type> <param>e</param>) -- announce selected route to the core <funcsect>Arguments <descrip> <tagp><type>struct babel_proto *</type> <param>p</param></tagp> Babel protocol instance <tagp><type>struct babel_entry *</type> <param>e</param></tagp> Babel route entry to announce </descrip> <funcsect>Description This function announces a Babel entry to the core if it has a selected incoming path, and retracts it otherwise. If the selected entry has infinite metric, the route is announced as unreachable. </function> <function><type>void</type> <funcdef>babel_select_route</funcdef> (<type>struct babel_entry *</type> <param>e</param>) -- select best route for given route entry <funcsect>Arguments <descrip> <tagp><type>struct babel_entry *</type> <param>e</param></tagp> Babel entry to select the best route for </descrip> <funcsect>Description Select the best feasible route for a given prefix among the routes received from peers, and propagate it to the nest. This just selects the feasible route with the lowest metric. If no feasible route is available for a prefix that previously had a route selected, a seqno request is sent to try to get a valid route. In the meantime, the route is marked as infeasible in the nest (to blackhole packets going to it, as per the RFC). If no feasible route is available, and no previous route is selected, the route is removed from the nest entirely. </function> <function><type>void</type> <funcdef>babel_send_update</funcdef> (<type>struct babel_iface *</type> <param>ifa</param>, <type>bird_clock_t</type> <param>changed</param>) -- send route table updates <funcsect>Arguments <descrip> <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp> Interface to transmit on <tagp><type>bird_clock_t</type> <param>changed</param></tagp> Only send entries changed since this time </descrip> <funcsect>Description This function produces update TLVs for all entries changed since the time indicated by the <struct/changed/ parameter and queues them for transmission on the selected interface. During the process, the feasibility distance for each transmitted entry is updated. </function> <function><type>void</type> <funcdef>babel_handle_update</funcdef> (<type>union babel_msg *</type> <param>m</param>, <type>struct babel_iface *</type> <param>ifa</param>) -- handle incoming route updates <funcsect>Arguments <descrip> <tagp><type>union babel_msg *</type> <param>m</param></tagp> Incoming update TLV <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp> Interface the update was received on </descrip> <funcsect>Description This function is called as a handler for update TLVs and handles the updating and maintenance of route entries in Babel's internal routing cache. The handling follows the actions described in the Babel RFC, and at the end of each update handling, <func/babel_select_route()/ is called on the affected entry to optionally update the selected routes and propagate them to the core. </function> <function><type>void</type> <funcdef>babel_iface_timer</funcdef> (<type>timer *</type> <param>t</param>) -- Babel interface timer handler <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>t</param></tagp> Timer </descrip> <funcsect>Description This function is called by the per-interface timer and triggers sending of periodic Hello's and both triggered and periodic updates. Periodic Hello's and updates are simply handled by setting the next_{hello,regular} variables on the interface, and triggering an update (and resetting the variable) whenever 'now' exceeds that value. For triggered updates, <func/babel_trigger_iface_update()/ will set the want_triggered field on the interface to a timestamp value. If this is set (and the next_triggered time has passed; this is a rate limiting mechanism), <func/babel_send_update()/ will be called with this timestamp as the second parameter. This causes updates to be send consisting of only the routes that have changed since the time saved in want_triggered. Mostly when an update is triggered, the route being modified will be set to the value of 'now' at the time of the trigger; the >= comparison for selecting which routes to send in the update will make sure this is included. </function> <function><type>void</type> <funcdef>babel_timer</funcdef> (<type>timer *</type> <param>t</param>) -- global timer hook <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>t</param></tagp> Timer </descrip> <funcsect>Description This function is called by the global protocol instance timer and handles expiration of routes and neighbours as well as pruning of the seqno request cache. </function> <function><type>uint</type> <funcdef>babel_write_queue</funcdef> (<type>struct babel_iface *</type> <param>ifa</param>, <type>list *</type> <param>queue</param>) -- Write a TLV queue to a transmission buffer <funcsect>Arguments <descrip> <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp> Interface holding the transmission buffer <tagp><type>list *</type> <param>queue</param></tagp> TLV queue to write (containing internal-format TLVs) </descrip> <funcsect>Description This function writes a packet to the interface transmission buffer with as many TLVs from the <struct/queue/ as will fit in the buffer. It returns the number of bytes written (NOT counting the packet header). The function is called by <func/babel_send_queue()/ and <func/babel_send_unicast()/ to construct packets for transmission, and uses per-TLV helper functions to convert the internal-format TLVs to their wire representations. The TLVs in the queue are freed after they are written to the buffer. </function> <function><type>void</type> <funcdef>babel_send_unicast</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>union babel_msg *</type> <param>msg</param></tagp> TLV to send <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp> Interface to send via <tagp><type>ip_addr</type> <param>dest</param></tagp> Destination of the TLV </descrip> <funcsect>Description This function is used to send a single TLV via unicast to a designated receiver. This is used for replying to certain incoming requests, and for sending unicast requests to refresh routes before they expire. </function> <function><type>void</type> <funcdef>babel_enqueue</funcdef> (<type>union babel_msg *</type> <param>msg</param>, <type>struct babel_iface *</type> <param>ifa</param>) -- enqueue a TLV for transmission on an interface <funcsect>Arguments <descrip> <tagp><type>union babel_msg *</type> <param>msg</param></tagp> TLV to enqueue (in internal TLV format) <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp> Interface to enqueue to </descrip> <funcsect>Description This function is called to enqueue a TLV for subsequent transmission on an interface. The transmission event is triggered whenever a TLV is enqueued; this ensures that TLVs will be transmitted in a timely manner, but that TLVs which are enqueued in rapid succession can be transmitted together in one packet. </function> <function><type>void</type> <funcdef>babel_process_packet</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct babel_pkt_header *</type> <param>pkt</param></tagp> Pointer to the packet data <tagp><type>int</type> <param>len</param></tagp> Length of received packet <tagp><type>ip_addr</type> <param>saddr</param></tagp> Address of packet sender <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp> Interface packet was received on. </descrip> <funcsect>Description This function is the main processing hook of incoming Babel packets. It checks that the packet header is well-formed, then processes the TLVs contained in the packet. This is done in two passes: First all TLVs are parsed into the internal TLV format. If a TLV parser fails, processing of the rest of the packet is aborted. After the parsing step, the TLV handlers are called for each parsed TLV in order. </function> <sect>Bidirectional Forwarding Detection The BFD protocol is implemented in three files: <tt>bfd.c</tt> containing the protocol logic and the protocol glue with BIRD core, <tt>packets.c</tt> handling BFD packet processing, RX, TX and protocol sockets. <tt>io.c</tt> then contains generic code for the event loop, threads and event sources (sockets, microsecond timers). This generic code will be merged to the main BIRD I/O code in the future. The BFD implementation uses a separate thread with an internal event loop for handling the protocol logic, which requires high-res and low-latency timing, so it is not affected by the rest of BIRD, which has several low-granularity hooks in the main loop, uses second-based timers and cannot offer good latency. The core of BFD protocol (the code related to BFD sessions, interfaces and packets) runs in the BFD thread, while the rest (the code related to BFD requests, BFD neighbors and the protocol glue) runs in the main thread. BFD sessions are represented by structure <struct/bfd_session/ that contains a state related to the session and two timers (TX timer for periodic packets and hold timer for session timeout). These sessions are allocated from <param/session_slab/ and are accessible by two hash tables, <param/session_hash_id/ (by session ID) and <param/session_hash_ip/ (by IP addresses of neighbors). Slab and both hashes are in the main protocol structure <struct/bfd_proto/. The protocol logic related to BFD sessions is implemented in internal functions bfd_session_*(), which are expected to be called from the context of BFD thread, and external functions <func/bfd_add_session()/, <func/bfd_remove_session()/ and <func/bfd_reconfigure_session()/, which form an interface to the BFD core for the rest and are expected to be called from the context of main thread. Each BFD session has an associated BFD interface, represented by structure <struct/bfd_iface/. A BFD interface contains a socket used for TX (the one for RX is shared in <struct/bfd_proto/), an interface configuration and reference counter. Compared to interface structures of other protocols, these structures are not created and removed based on interface notification events, but according to the needs of BFD sessions. When a new session is created, it requests a proper BFD interface by function <func/bfd_get_iface()/, which either finds an existing one in <struct/iface_list/ (from <struct/bfd_proto/) or allocates a new one. When a session is removed, an associated iface is discharged by <func/bfd_free_iface()/. BFD requests are the external API for the other protocols. When a protocol wants a BFD session, it calls <func/bfd_request_session()/, which creates a structure <struct/bfd_request/ containing approprite information and an notify hook. This structure is a resource associated with the caller's resource pool. When a BFD protocol is available, a BFD request is submitted to the protocol, an appropriate BFD session is found or created and the request is attached to the session. When a session changes state, all attached requests (and related protocols) are notified. Note that BFD requests do not depend on BFD protocol running. When the BFD protocol is stopped or removed (or not available from beginning), related BFD requests are stored in <param/bfd_wait_list/, where waits for a new protocol. BFD neighbors are just a way to statically configure BFD sessions without requests from other protocol. Structures <struct/bfd_neighbor/ are part of BFD configuration (like static routes in the static protocol). BFD neighbors are handled by BFD protocol like it is a BFD client -- when a BFD neighbor is ready, the protocol just creates a BFD request like any other protocol. The protocol uses a new generic event loop (structure <struct/birdloop/) from <tt>io.c</tt>, which supports sockets, timers and events like the main loop. Timers (structure <struct/timer2/) are new microsecond based timers, while sockets and events are the same. A birdloop is associated with a thread (field <param/thread/) in which event hooks are executed. Most functions for setting event sources (like <func/sk_start()/ or <func/tm2_start()/) must be called from the context of that thread. Birdloop allows to temporarily acquire the context of that thread for the main thread by calling <func/birdloop_enter()/ and then <func/birdloop_leave()/, which also ensures mutual exclusion with all event hooks. Note that resources associated with a birdloop (like timers) should be attached to the independent resource pool, detached from the main resource tree. There are two kinds of interaction between the BFD core (running in the BFD thread) and the rest of BFD (running in the main thread). The first kind are configuration calls from main thread to the BFD thread (like <func/bfd_add_session()/). These calls are synchronous and use <func/birdloop_enter()/ mechanism for mutual exclusion. The second kind is a notification about session changes from the BFD thread to the main thread. This is done in an asynchronous way, sesions with pending notifications are linked (in the BFD thread) to <param/notify_list/ in <struct/bfd_proto/, and then <func/bfd_notify_hook()/ in the main thread is activated using <func/bfd_notify_kick()/ and a pipe. The hook then processes scheduled sessions and calls hooks from associated BFD requests. This <param/notify_list/ (and state fields in structure <struct/bfd_session/) is protected by a spinlock in <struct/bfd_proto/ and functions <func/bfd_lock_sessions()/ / <func/bfd_unlock_sessions()/. There are few data races (accessing <param/p/->p.debug from <func/TRACE()/ from the BFD thread and accessing some some private fields of <const/bfd_session/ from <func/bfd_show_sessions()/ from the main thread, but these are harmless (i hope). TODO: document functions and access restrictions for fields in BFD structures. Supported standards: - RFC 5880 - main BFD standard - RFC 5881 - BFD for IP links - RFC 5882 - generic application of BFD - RFC 5883 - BFD for multihop paths <sect>Border Gateway Protocol The BGP protocol is implemented in three parts: <tt>bgp.c</tt> which takes care of the connection and most of the interface with BIRD core, <tt>packets.c</tt> handling both incoming and outgoing BGP packets and <tt>attrs.c</tt> containing functions for manipulation with BGP attribute lists. As opposed to the other existing routing daemons, BIRD has a sophisticated core architecture which is able to keep all the information needed by BGP in the primary routing table, therefore no complex data structures like a central BGP table are needed. This increases memory footprint of a BGP router with many connections, but not too much and, which is more important, it makes BGP much easier to implement. Each instance of BGP (corresponding to a single BGP peer) is described by a <struct/bgp_proto/ structure to which are attached individual connections represented by <struct/bgp_connection/ (usually, there exists only one connection, but during BGP session setup, there can be more of them). The connections are handled according to the BGP state machine defined in the RFC with all the timers and all the parameters configurable. In incoming direction, we listen on the connection's socket and each time we receive some input, we pass it to <func/bgp_rx()/. It decodes packet headers and the markers and passes complete packets to <func/bgp_rx_packet()/ which distributes the packet according to its type. In outgoing direction, we gather all the routing updates and sort them to buckets (<struct/bgp_bucket/) according to their attributes (we keep a hash table for fast comparison of <struct/rta/'s and a <struct/fib/ which helps us to find if we already have another route for the same destination queued for sending, so that we can replace it with the new one immediately instead of sending both updates). There also exists a special bucket holding all the route withdrawals which cannot be queued anywhere else as they don't have any attributes. If we have any packet to send (due to either new routes or the connection tracking code wanting to send a Open, Keepalive or Notification message), we call <func/bgp_schedule_packet()/ which sets the corresponding bit in a <param/packet_to_send/ bit field in <struct/bgp_conn/ and as soon as the transmit socket buffer becomes empty, we call <func/bgp_fire_tx()/. It inspects state of all the packet type bits and calls the corresponding <func/bgp_create_xx()/ functions, eventually rescheduling the same packet type if we have more data of the same type to send. The processing of attributes consists of two functions: <func/bgp_decode_attrs()/ for checking of the attribute blocks and translating them to the language of BIRD's extended attributes and <func/bgp_encode_attrs()/ which does the converse. Both functions are built around a <param/bgp_attr_table/ array describing all important characteristics of all known attributes. Unknown transitive attributes are attached to the route as <const/EAF_TYPE_OPAQUE/ byte streams. BGP protocol implements graceful restart in both restarting (local restart) and receiving (neighbor restart) roles. The first is handled mostly by the graceful restart code in the nest, BGP protocol just handles capabilities, sets <param/gr_wait/ and locks graceful restart until end-of-RIB mark is received. The second is implemented by internal restart of the BGP state to <const/BS_IDLE/ and protocol state to <const/PS_START/, but keeping the protocol up from the core point of view and therefore maintaining received routes. Routing table refresh cycle (<func/rt_refresh_begin()/, <func/rt_refresh_end()/) is used for removing stale routes after reestablishment of BGP session during graceful restart. <function><type>int</type> <funcdef>bgp_open</funcdef> (<type>struct bgp_proto *</type> <param>p</param>) -- open a BGP instance <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance </descrip> <funcsect>Description This function allocates and configures shared BGP resources. Should be called as the last step during initialization (when lock is acquired and neighbor is ready). When error, state changed to PS_DOWN, -1 is returned and caller should return immediately. </function> <function><type>void</type> <funcdef>bgp_close</funcdef> (<type>struct bgp_proto *</type> <param>p</param>, <type>int</type> <param>apply_md5</param>) -- close a BGP instance <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance <tagp><type>int</type> <param>apply_md5</param></tagp> 0 to disable unsetting MD5 auth </descrip> <funcsect>Description This function frees and deconfigures shared BGP resources. <param/apply_md5/ is set to 0 when bgp_close is called as a cleanup from failed <func/bgp_open()/. </function> <function><type>void</type> <funcdef>bgp_start_timer</funcdef> (<type>timer *</type> <param>t</param>, <type>int</type> <param>value</param>) -- start a BGP timer <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>t</param></tagp> timer <tagp><type>int</type> <param>value</param></tagp> time to fire (0 to disable the timer) </descrip> <funcsect>Description This functions calls <func/tm_start()/ on <param/t/ with time <param/value/ and the amount of randomization suggested by the BGP standard. Please use it for all BGP timers. </function> <function><type>void</type> <funcdef>bgp_close_conn</funcdef> (<type>struct bgp_conn *</type> <param>conn</param>) -- close a BGP connection <funcsect>Arguments <descrip> <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp> connection to close </descrip> <funcsect>Description This function takes a connection described by the <struct/bgp_conn/ structure, closes its socket and frees all resources associated with it. </function> <function><type>void</type> <funcdef>bgp_update_startup_delay</funcdef> (<type>struct bgp_proto *</type> <param>p</param>) -- update a startup delay <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance </descrip> <funcsect>Description This function updates a startup delay that is used to postpone next BGP connect. It also handles disable_after_error and might stop BGP instance when error happened and disable_after_error is on. It should be called when BGP protocol error happened. </function> <function><type>void</type> <funcdef>bgp_handle_graceful_restart</funcdef> (<type>struct bgp_proto *</type> <param>p</param>) -- handle detected BGP graceful restart <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance </descrip> <funcsect>Description This function is called when a BGP graceful restart of the neighbor is detected (when the TCP connection fails or when a new TCP connection appears). The function activates processing of the restart - starts routing table refresh cycle and activates BGP restart timer. The protocol state goes back to <const/PS_START/, but changing BGP state back to <const/BS_IDLE/ is left for the caller. </function> <function><type>void</type> <funcdef>bgp_graceful_restart_done</funcdef> (<type>struct bgp_proto *</type> <param>p</param>) -- finish active BGP graceful restart <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance </descrip> <funcsect>Description This function is called when the active BGP graceful restart of the neighbor should be finished - either successfully (the neighbor sends all paths and reports end-of-RIB on the new session) or unsuccessfully (the neighbor does not support BGP graceful restart on the new session). The function ends routing table refresh cycle and stops BGP restart timer. </function> <function><type>void</type> <funcdef>bgp_graceful_restart_timeout</funcdef> (<type>timer *</type> <param>t</param>) -- timeout of graceful restart 'restart timer' <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>t</param></tagp> timer </descrip> <funcsect>Description This function is a timeout hook for <param/gr_timer/, implementing BGP restart time limit for reestablisment of the BGP session after the graceful restart. When fired, we just proceed with the usual protocol restart. </function> <function><type>void</type> <funcdef>bgp_refresh_begin</funcdef> (<type>struct bgp_proto *</type> <param>p</param>) -- start incoming enhanced route refresh sequence <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance </descrip> <funcsect>Description This function is called when an incoming enhanced route refresh sequence is started by the neighbor, demarcated by the BoRR packet. The function updates the load state and starts the routing table refresh cycle. Note that graceful restart also uses routing table refresh cycle, but RFC 7313 and load states ensure that these two sequences do not overlap. </function> <function><type>void</type> <funcdef>bgp_refresh_end</funcdef> (<type>struct bgp_proto *</type> <param>p</param>) -- finish incoming enhanced route refresh sequence <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance </descrip> <funcsect>Description This function is called when an incoming enhanced route refresh sequence is finished by the neighbor, demarcated by the EoRR packet. The function updates the load state and ends the routing table refresh cycle. Routes not received during the sequence are removed by the nest. </function> <function><type>void</type> <funcdef>bgp_connect</funcdef> (<type>struct bgp_proto *</type> <param>p</param>) -- initiate an outgoing connection <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance </descrip> <funcsect>Description The <func/bgp_connect()/ function creates a new <struct/bgp_conn/ and initiates a TCP connection to the peer. The rest of connection setup is governed by the BGP state machine as described in the standard. </function> <function><type>struct bgp_proto *</type> <funcdef>bgp_find_proto</funcdef> (<type>sock *</type> <param>sk</param>) -- find existing proto for incoming connection <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>sk</param></tagp> TCP socket </descrip> </function> <function><type>int</type> <funcdef>bgp_incoming_connection</funcdef> (<type>sock *</type> <param>sk</param>, <type>uint dummy</type> <param>UNUSED</param>) -- handle an incoming connection <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>sk</param></tagp> TCP socket <tagp><type>uint dummy</type> <param>UNUSED</param></tagp> -- undescribed -- </descrip> <funcsect>Description This function serves as a socket hook for accepting of new BGP connections. It searches a BGP instance corresponding to the peer which has connected and if such an instance exists, it creates a <struct/bgp_conn/ structure, attaches it to the instance and either sends an Open message or (if there already is an active connection) it closes the new connection by sending a Notification message. </function> <function><type>void</type> <funcdef>bgp_error</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct bgp_conn *</type> <param>c</param></tagp> connection <tagp><type>unsigned</type> <param>code</param></tagp> error code (according to the RFC) <tagp><type>unsigned</type> <param>subcode</param></tagp> error sub-code <tagp><type>byte *</type> <param>data</param></tagp> data to be passed in the Notification message <tagp><type>int</type> <param>len</param></tagp> length of the data </descrip> <funcsect>Description <func/bgp_error()/ sends a notification packet to tell the other side that a protocol error has occurred (including the data considered erroneous if possible) and closes the connection. </function> <function><type>void</type> <funcdef>bgp_store_error</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance <tagp><type>struct bgp_conn *</type> <param>c</param></tagp> connection <tagp><type>u8</type> <param>class</param></tagp> error class (BE_xxx constants) <tagp><type>u32</type> <param>code</param></tagp> error code (class specific) </descrip> <funcsect>Description <func/bgp_store_error()/ decides whether given error is interesting enough and store that error to last_error variables of <param/p/ </function> <function><type>int</type> <funcdef>bgp_fire_tx</funcdef> (<type>struct bgp_conn *</type> <param>conn</param>) -- transmit packets <funcsect>Arguments <descrip> <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp> connection </descrip> <funcsect>Description Whenever the transmit buffers of the underlying TCP connection are free and we have any packets queued for sending, the socket functions call <func/bgp_fire_tx()/ which takes care of selecting the highest priority packet queued (Notification > Keepalive > Open > Update), assembling its header and body and sending it to the connection. </function> <function><type>void</type> <funcdef>bgp_schedule_packet</funcdef> (<type>struct bgp_conn *</type> <param>conn</param>, <type>int</type> <param>type</param>) -- schedule a packet for transmission <funcsect>Arguments <descrip> <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp> connection <tagp><type>int</type> <param>type</param></tagp> packet type </descrip> <funcsect>Description Schedule a packet of type <param/type/ to be sent as soon as possible. </function> <function><type>const char *</type> <funcdef>bgp_error_dsc</funcdef> (<type>unsigned</type> <param>code</param>, <type>unsigned</type> <param>subcode</param>) -- return BGP error description <funcsect>Arguments <descrip> <tagp><type>unsigned</type> <param>code</param></tagp> BGP error code <tagp><type>unsigned</type> <param>subcode</param></tagp> BGP error subcode </descrip> <funcsect>Description <func/bgp_error_dsc()/ returns error description for BGP errors which might be static string or given temporary buffer. </function> <function><type>void</type> <funcdef>bgp_rx_packet</funcdef> (<type>struct bgp_conn *</type> <param>conn</param>, <type>byte *</type> <param>pkt</param>, <type>unsigned</type> <param>len</param>) -- handle a received packet <funcsect>Arguments <descrip> <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp> BGP connection <tagp><type>byte *</type> <param>pkt</param></tagp> start of the packet <tagp><type>unsigned</type> <param>len</param></tagp> packet size </descrip> <funcsect>Description <func/bgp_rx_packet()/ takes a newly received packet and calls the corresponding packet handler according to the packet type. </function> <function><type>int</type> <funcdef>bgp_rx</funcdef> (<type>sock *</type> <param>sk</param>, <type>uint</type> <param>size</param>) -- handle received data <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>sk</param></tagp> socket <tagp><type>uint</type> <param>size</param></tagp> amount of data received </descrip> <funcsect>Description <func/bgp_rx()/ is called by the socket layer whenever new data arrive from the underlying TCP connection. It assembles the data fragments to packets, checks their headers and framing and passes complete packets to <func/bgp_rx_packet()/. </function> <function><type>uint</type> <funcdef>bgp_encode_attrs</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> BGP instance (or NULL) <tagp><type>byte *</type> <param>w</param></tagp> buffer <tagp><type>ea_list *</type> <param>attrs</param></tagp> a list of extended attributes <tagp><type>int</type> <param>remains</param></tagp> remaining space in the buffer </descrip> <funcsect>Description The <func/bgp_encode_attrs()/ function takes a list of extended attributes and converts it to its BGP representation (a part of an Update message). <funcsect>Result Length of the attribute block generated or -1 if not enough space. </function> <function><type>struct rta *</type> <funcdef>bgp_decode_attrs</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp> connection <tagp><type>byte *</type> <param>attr</param></tagp> start of attribute block <tagp><type>uint</type> <param>len</param></tagp> length of attribute block <tagp><type>struct linpool *</type> <param>pool</param></tagp> linear pool to make all the allocations in <tagp><type>int</type> <param>mandatory</param></tagp> 1 iff presence of mandatory attributes has to be checked </descrip> <funcsect>Description This function takes a BGP attribute block (a part of an Update message), checks its consistency and converts it to a list of BIRD route attributes represented by a <struct/rta/. </function> <sect>Multi-Threaded Routing Toolkit (MRT) protocol The MRT protocol is implemented in just one file: <tt>mrt.c</tt>. It contains of several parts: Generic functions for preparing MRT messages in a buffer, functions for MRT table dump (called from timer or CLI), functions for MRT BGP4MP dump (called from BGP), and the usual protocol glue. For the MRT table dump, the key structure is struct mrt_table_dump_state, which contains all necessary data and created when the MRT dump cycle is started for the duration of the MRT dump. The MBGP4MP dump is currently not bound to MRT protocol instance and uses the config->mrtdump_file fd. The protocol is simple, just periodically scans routing table and export it to a file. It does not use the regular update mechanism, but a direct access in order to handle iteration through multiple routing tables. The table dump needs to dump all peers first and then use indexes to address the peers, we use a hash table (<param/peer_hash/) to find peer index based on BGP protocol key attributes. One thing worth documenting is the locking. During processing, the currently processed table (<param/table/ field in the state structure) is locked and also the explicitly named table is locked (<param/table_ptr/ field in the state structure) if specified. Between dumps no table is locked. Also the current config is locked (by <func/config_add_obstacle()/) during table dumps as some data (strings, filters) are shared from the config and the running table dump may be interrupted by reconfiguration. Supported standards: - RFC 6396 - MRT format standard - RFC 8050 - ADD_PATH extension <sect>Open Shortest Path First (OSPF) The OSPF protocol is quite complicated and its complex implemenation is split to many files. In <tt>ospf.c</tt>, you will find mainly the interface for communication with the core (e.g., reconfiguration hooks, shutdown and initialisation and so on). File <tt>iface.c</tt> contains the interface state machine and functions for allocation and deallocation of OSPF's interface data structures. Source <tt>neighbor.c</tt> includes the neighbor state machine and functions for election of Designated Router and Backup Designated router. In <tt>packet.c</tt>, you will find various functions for sending and receiving generic OSPF packets. There are also routines for authentication and checksumming. In <tt>hello.c</tt>, there are routines for sending and receiving of hello packets as well as functions for maintaining wait times and the inactivity timer. Files <tt>lsreq.c</tt>, <tt>lsack.c</tt>, <tt>dbdes.c</tt> contain functions for sending and receiving of link-state requests, link-state acknowledgements and database descriptions respectively. In <tt>lsupd.c</tt>, there are functions for sending and receiving of link-state updates and also the flooding algorithm. Source <tt>topology.c</tt> is a place where routines for searching LSAs in the link-state database, adding and deleting them reside, there also are functions for originating of various types of LSAs (router LSA, net LSA, external LSA). File <tt>rt.c</tt> contains routines for calculating the routing table. <tt>lsalib.c</tt> is a set of various functions for working with the LSAs (endianity conversions, calculation of checksum etc.). One instance of the protocol is able to hold LSA databases for multiple OSPF areas, to exchange routing information between multiple neighbors and to calculate the routing tables. The core structure is <struct/ospf_proto/ to which multiple <struct/ospf_area/ and <struct/ospf_iface/ structures are connected. <struct/ospf_proto/ is also connected to <struct/top_hash_graph/ which is a dynamic hashing structure that describes the link-state database. It allows fast search, addition and deletion. Each LSA is kept in two pieces: header and body. Both of them are kept in the endianity of the CPU. In OSPFv2 specification, it is implied that there is one IP prefix for each physical network/interface (unless it is an ptp link). But in modern systems, there might be more independent IP prefixes associated with an interface. To handle this situation, we have one <struct/ospf_iface/ for each active IP prefix (instead for each active iface); This behaves like virtual interface for the purpose of OSPF. If we receive packet, we associate it with a proper virtual interface mainly according to its source address. OSPF keeps one socket per <struct/ospf_iface/. This allows us (compared to one socket approach) to evade problems with a limit of multicast groups per socket and with sending multicast packets to appropriate interface in a portable way. The socket is associated with underlying physical iface and should not receive packets received on other ifaces (unfortunately, this is not true on BSD). Generally, one packet can be received by more sockets (for example, if there are more <struct/ospf_iface/ on one physical iface), therefore we explicitly filter received packets according to src/dst IP address and received iface. Vlinks are implemented using particularly degenerate form of <struct/ospf_iface/, which has several exceptions: it does not have its iface or socket (it copies these from 'parent' <struct/ospf_iface/) and it is present in iface list even when down (it is not freed in <func/ospf_iface_down()/). The heart beat of ospf is <func/ospf_disp()/. It is called at regular intervals (<struct/ospf_proto/->tick). It is responsible for aging and flushing of LSAs in the database, updating topology information in LSAs and for routing table calculation. To every <struct/ospf_iface/, we connect one or more <struct/ospf_neighbor/'s -- a structure containing many timers and queues for building adjacency and for exchange of routing messages. BIRD's OSPF implementation respects RFC2328 in every detail, but some of internal algorithms do differ. The RFC recommends making a snapshot of the link-state database when a new adjacency is forming and sending the database description packets based on the information in this snapshot. The database can be quite large in some networks, so rather we walk through a <struct/slist/ structure which allows us to continue even if the actual LSA we were working with is deleted. New LSAs are added at the tail of this <struct/slist/. We also do not keep a separate OSPF routing table, because the core helps us by being able to recognize when a route is updated to an identical one and it suppresses the update automatically. Due to this, we can flush all the routes we have recalculated and also those we have deleted to the core's routing table and the core will take care of the rest. This simplifies the process and conserves memory. Supported standards: - RFC 2328 - main OSPFv2 standard - RFC 5340 - main OSPFv3 standard - RFC 3101 - OSPFv2 NSSA areas - RFC 6549 - OSPFv2 multi-instance extensions - RFC 6987 - OSPF stub router advertisement <function><type>void</type> <funcdef>ospf_disp</funcdef> (<type>timer *</type> <param>timer</param>) -- invokes routing table calculation, aging and also <func/area_disp()/ <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>timer</param></tagp> timer usually called every <param/ospf_proto/->tick second, <param/timer/->data point to <param/ospf_proto/ </descrip> </function> <function><type>int</type> <funcdef>ospf_import_control</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>P</param></tagp> OSPF protocol instance <tagp><type>rte **</type> <param>new</param></tagp> the new route <tagp><type>ea_list **</type> <param>attrs</param></tagp> list of attributes <tagp><type>struct linpool *</type> <param>pool</param></tagp> pool for allocation of attributes </descrip> <funcsect>Description Its quite simple. It does not accept our own routes and leaves the decision on import to the filters. </function> <function><type>int</type> <funcdef>ospf_shutdown</funcdef> (<type>struct proto *</type> <param>P</param>) -- Finish of OSPF instance <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>P</param></tagp> OSPF protocol instance </descrip> <funcsect>Description RFC does not define any action that should be taken before router shutdown. To make my neighbors react as fast as possible, I send them hello packet with empty neighbor list. They should start their neighbor state machine with event <const/NEIGHBOR_1WAY/. </function> <function><type>int</type> <funcdef>ospf_reconfigure</funcdef> (<type>struct proto *</type> <param>P</param>, <type>struct proto_config *</type> <param>c</param>) -- reconfiguration hook <funcsect>Arguments <descrip> <tagp><type>struct proto *</type> <param>P</param></tagp> current instance of protocol (with old configuration) <tagp><type>struct proto_config *</type> <param>c</param></tagp> new configuration requested by user </descrip> <funcsect>Description This hook tries to be a little bit intelligent. Instance of OSPF will survive change of many constants like hello interval, password change, addition or deletion of some neighbor on nonbroadcast network, cost of interface, etc. </function> <function><type>struct top_hash_entry *</type> <funcdef>ospf_install_lsa</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> OSPF protocol instance <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp> LSA header <tagp><type>u32</type> <param>type</param></tagp> type of LSA <tagp><type>u32</type> <param>domain</param></tagp> domain of LSA <tagp><type>void *</type> <param>body</param></tagp> pointer to LSA body </descrip> <funcsect>Description This function ensures installing new LSA received in LS update into LSA database. Old instance is replaced. Several actions are taken to detect if new routing table calculation is necessary. This is described in 13.2 of RFC 2328. This function is for received LSA only, locally originated LSAs are installed by <func/ospf_originate_lsa()/. The LSA body in <param/body/ is expected to be mb_allocated by the caller and its ownership is transferred to the LSA entry structure. </function> <function><type>void</type> <funcdef>ospf_advance_lsa</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> OSPF protocol instance <tagp><type>struct top_hash_entry *</type> <param>en</param></tagp> current LSA entry or NULL <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp> new LSA header <tagp><type>u32</type> <param>type</param></tagp> type of LSA <tagp><type>u32</type> <param>domain</param></tagp> domain of LSA <tagp><type>void *</type> <param>body</param></tagp> pointer to LSA body </descrip> <funcsect>Description This function handles received unexpected self-originated LSA (<param/lsa/, <param/body/) by either advancing sequence number of the local LSA instance (<param/en/) and propagating it, or installing the received LSA and immediately flushing it (if there is no local LSA; i.e., <param/en/ is NULL or MaxAge). The LSA body in <param/body/ is expected to be mb_allocated by the caller and its ownership is transferred to the LSA entry structure or it is freed. </function> <function><type>struct top_hash_entry *</type> <funcdef>ospf_originate_lsa</funcdef> (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_new_lsa *</type> <param>lsa</param>) -- originate new LSA <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> OSPF protocol instance <tagp><type>struct ospf_new_lsa *</type> <param>lsa</param></tagp> New LSA specification </descrip> <funcsect>Description This function prepares a new LSA, installs it into the LSA database and floods it. If the new LSA cannot be originated now (because the old instance was originated within MinLSInterval, or because the LSA seqnum is currently wrapping), the origination is instead scheduled for later. If the new LSA is equivalent to the current LSA, the origination is skipped. In all cases, the corresponding LSA entry is returned. The new LSA is based on the LSA specification (<param/lsa/) and the LSA body from lsab buffer of <param/p/, which is emptied after the call. The opposite of this function is <func/ospf_flush_lsa()/. </function> <function><type>void</type> <funcdef>ospf_flush_lsa</funcdef> (<type>struct ospf_proto *</type> <param>p</param>, <type>struct top_hash_entry *</type> <param>en</param>) -- flush LSA from OSPF domain <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> OSPF protocol instance <tagp><type>struct top_hash_entry *</type> <param>en</param></tagp> LSA entry to flush </descrip> <funcsect>Description This function flushes <param/en/ from the OSPF domain by setting its age to <const/LSA_MAXAGE/ and flooding it. That also triggers subsequent events in LSA lifecycle leading to removal of the LSA from the LSA database (e.g. the LSA content is freed when flushing is acknowledged by neighbors). The function does nothing if the LSA is already being flushed. LSA entries are not immediately removed when being flushed, the caller may assume that <param/en/ still exists after the call. The function is the opposite of <func/ospf_originate_lsa()/ and is supposed to do the right thing even in cases of postponed origination. </function> <function><type>void</type> <funcdef>ospf_update_lsadb</funcdef> (<type>struct ospf_proto *</type> <param>p</param>) -- update LSA database <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> OSPF protocol instance </descrip> <funcsect>Description This function is periodicaly invoked from <func/ospf_disp()/. It does some periodic or postponed processing related to LSA entries. It originates postponed LSAs scheduled by <func/ospf_originate_lsa()/, It continues in flushing processes started by <func/ospf_flush_lsa()/. It also periodically refreshs locally originated LSAs -- when the current instance is older <const/LSREFRESHTIME/, a new instance is originated. Finally, it also ages stored LSAs and flushes ones that reached <const/LSA_MAXAGE/. The RFC 2328 says that a router should periodically check checksums of all stored LSAs to detect hardware problems. This is not implemented. </function> <function><type>void</type> <funcdef>ospf_originate_ext_lsa</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> OSPF protocol instance <tagp><type>struct ospf_area *</type> <param>oa</param></tagp> ospf_area for which LSA is originated <tagp><type>ort *</type> <param>nf</param></tagp> network prefix and mask <tagp><type>u8</type> <param>mode</param></tagp> the mode of the LSA (LSA_M_EXPORT or LSA_M_RTCALC) <tagp><type>u32</type> <param>metric</param></tagp> the metric of a route <tagp><type>u32</type> <param>ebit</param></tagp> E-bit for route metric (bool) <tagp><type>ip_addr</type> <param>fwaddr</param></tagp> the forwarding address <tagp><type>u32</type> <param>tag</param></tagp> the route tag <tagp><type>int</type> <param>pbit</param></tagp> P-bit for NSSA LSAs (bool), ignored for external LSAs </descrip> <funcsect>Description If I receive a message that new route is installed, I try to originate an external LSA. If <param/oa/ is an NSSA area, NSSA-LSA is originated instead. <param/oa/ should not be a stub area. <param/src/ does not specify whether the LSA is external or NSSA, but it specifies the source of origination - the export from <func/ospf_rt_notify()/, or the NSSA-EXT translation. </function> <function><type>struct top_graph *</type> <funcdef>ospf_top_new</funcdef> (<type>struct ospf_proto *p UNUSED4</type> <param>UNUSED6</param>, <type>pool *</type> <param>pool</param>) -- allocated new topology database <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *p UNUSED4</type> <param>UNUSED6</param></tagp> -- undescribed -- <tagp><type>pool *</type> <param>pool</param></tagp> pool for allocation </descrip> <funcsect>Description This dynamically hashed structure is used for keeping LSAs. Mainly it is used for the LSA database of the OSPF protocol, but also for LSA retransmission and request lists of OSPF neighbors. </function> <function><type>void</type> <funcdef>ospf_neigh_chstate</funcdef> (<type>struct ospf_neighbor *</type> <param>n</param>, <type>u8</type> <param>state</param>) -- handles changes related to new or lod state of neighbor <funcsect>Arguments <descrip> <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp> OSPF neighbor <tagp><type>u8</type> <param>state</param></tagp> new state </descrip> <funcsect>Description Many actions have to be taken acording to a change of state of a neighbor. It starts rxmt timers, call interface state machine etc. </function> <function><type>void</type> <funcdef>ospf_neigh_sm</funcdef> (<type>struct ospf_neighbor *</type> <param>n</param>, <type>int</type> <param>event</param>) -- ospf neighbor state machine <funcsect>Arguments <descrip> <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp> neighor <tagp><type>int</type> <param>event</param></tagp> actual event </descrip> <funcsect>Description This part implements the neighbor state machine as described in 10.3 of RFC 2328. The only difference is that state <const/NEIGHBOR_ATTEMPT/ is not used. We discover neighbors on nonbroadcast networks in the same way as on broadcast networks. The only difference is in sending hello packets. These are sent to IPs listed in <param/ospf_iface/->nbma_list . </function> <function><type>void</type> <funcdef>ospf_dr_election</funcdef> (<type>struct ospf_iface *</type> <param>ifa</param>) -- (Backup) Designed Router election <funcsect>Arguments <descrip> <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp> actual interface </descrip> <funcsect>Description When the wait timer fires, it is time to elect (Backup) Designated Router. Structure describing me is added to this list so every electing router has the same list. Backup Designated Router is elected before Designated Router. This process is described in 9.4 of RFC 2328. The function is supposed to be called only from <func/ospf_iface_sm()/ as a part of the interface state machine. </function> <function><type>void</type> <funcdef>ospf_iface_chstate</funcdef> (<type>struct ospf_iface *</type> <param>ifa</param>, <type>u8</type> <param>state</param>) -- handle changes of interface state <funcsect>Arguments <descrip> <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp> OSPF interface <tagp><type>u8</type> <param>state</param></tagp> new state </descrip> <funcsect>Description Many actions must be taken according to interface state changes. New network LSAs must be originated, flushed, new multicast sockets to listen for messages for <const/ALLDROUTERS/ have to be opened, etc. </function> <function><type>void</type> <funcdef>ospf_iface_sm</funcdef> (<type>struct ospf_iface *</type> <param>ifa</param>, <type>int</type> <param>event</param>) -- OSPF interface state machine <funcsect>Arguments <descrip> <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp> OSPF interface <tagp><type>int</type> <param>event</param></tagp> event comming to state machine </descrip> <funcsect>Description This fully respects 9.3 of RFC 2328 except we have slightly different handling of <const/DOWN/ and <const/LOOP/ state. We remove intefaces that are <const/DOWN/. <const/DOWN/ state is used when an interface is waiting for a lock. <const/LOOP/ state is used when an interface does not have a link. </function> <function><type>int</type> <funcdef>ospf_rx_hook</funcdef> (<type>sock *</type> <param>sk</param>, <type>uint</type> <param>len</param>) <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>sk</param></tagp> socket we received the packet. <tagp><type>uint</type> <param>len</param></tagp> size of the packet </descrip> <funcsect>Description This is the entry point for messages from neighbors. Many checks (like authentication, checksums, size) are done before the packet is passed to non generic functions. </function> <function><type>int</type> <funcdef>lsa_validate</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp> LSA header <tagp><type>u32</type> <param>lsa_type</param></tagp> one of <const/LSA_T_xxx/ <tagp><type>int</type> <param>ospf2</param></tagp> <const/true/ means OSPF version 2, <const/false/ means OSPF version 3 <tagp><type>void *</type> <param>body</param></tagp> pointer to LSA body </descrip> <funcsect>Description Checks internal structure of given LSA body (minimal length, consistency). Returns true if valid. </function> <function><type>void</type> <funcdef>ospf_send_dbdes</funcdef> (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_neighbor *</type> <param>n</param>) -- transmit database description packet <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> OSPF protocol instance <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp> neighbor </descrip> <funcsect>Description Sending of a database description packet is described in 10.8 of RFC 2328. Reception of each packet is acknowledged in the sequence number of another. When I send a packet to a neighbor I keep a copy in a buffer. If the neighbor does not reply, I don't create a new packet but just send the content of the buffer. </function> <function><type>void</type> <funcdef>ospf_rt_spf</funcdef> (<type>struct ospf_proto *</type> <param>p</param>) -- calculate internal routes <funcsect>Arguments <descrip> <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> OSPF protocol instance </descrip> <funcsect>Description Calculation of internal paths in an area is described in 16.1 of RFC 2328. It's based on Dijkstra's shortest path tree algorithms. This function is invoked from <func/ospf_disp()/. </function> <sect>Pipe The Pipe protocol is very simple. It just connects to two routing tables using <func/proto_add_announce_hook()/ and whenever it receives a <func/rt_notify()/ about a change in one of the tables, it converts it to a <func/rte_update()/ in the other one. To avoid pipe loops, Pipe keeps a `being updated' flag in each routing table. A pipe has two announce hooks, the first connected to the main table, the second connected to the peer table. When a new route is announced on the main table, it gets checked by an export filter in ahook 1, and, after that, it is announced to the peer table via <func/rte_update()/, an import filter in ahook 2 is called. When a new route is announced in the peer table, an export filter in ahook2 and an import filter in ahook 1 are used. Oviously, there is no need in filtering the same route twice, so both import filters are set to accept, while user configured 'import' and 'export' filters are used as export filters in ahooks 2 and 1. Route limits are handled similarly, but on the import side of ahooks. <sect>Routing Information Protocol (RIP) The RIP protocol is implemented in two files: <tt>rip.c</tt> containing the protocol logic, route management and the protocol glue with BIRD core, and <tt>packets.c</tt> handling RIP packet processing, RX, TX and protocol sockets. Each instance of RIP is described by a structure <struct/rip_proto/, which contains an internal RIP routing table, a list of protocol interfaces and the main timer responsible for RIP routing table cleanup. RIP internal routing table contains incoming and outgoing routes. For each network (represented by structure <struct/rip_entry/) there is one outgoing route stored directly in <struct/rip_entry/ and an one-way linked list of incoming routes (structures <struct/rip_rte/). The list contains incoming routes from different RIP neighbors, but only routes with the lowest metric are stored (i.e., all stored incoming routes have the same metric). Note that RIP itself does not select outgoing route, that is done by the core routing table. When a new incoming route is received, it is propagated to the RIP table by <func/rip_update_rte()/ and possibly stored in the list of incoming routes. Then the change may be propagated to the core by <func/rip_announce_rte()/. The core selects the best route and propagate it to RIP by <func/rip_rt_notify()/, which updates outgoing route part of <struct/rip_entry/ and possibly triggers route propagation by <func/rip_trigger_update()/. RIP interfaces are represented by structures <struct/rip_iface/. A RIP interface contains a per-interface socket, a list of associated neighbors, interface configuration, and state information related to scheduled interface events and running update sessions. RIP interfaces are added and removed based on core interface notifications. There are two RIP interface events - regular updates and triggered updates. Both are managed from the RIP interface timer (<func/rip_iface_timer()/). Regular updates are called at fixed interval and propagate the whole routing table, while triggered updates are scheduled by <func/rip_trigger_update()/ due to some routing table change and propagate only the routes modified since the time they were scheduled. There are also unicast-destined requested updates, but these are sent directly as a reaction to received RIP request message. The update session is started by <func/rip_send_table()/. There may be at most one active update session per interface, as the associated state (including the fib iterator) is stored directly in <struct/rip_iface/ structure. RIP neighbors are represented by structures <struct/rip_neighbor/. Compared to neighbor handling in other routing protocols, RIP does not have explicit neighbor discovery and adjacency maintenance, which makes the <struct/rip_neighbor/ related code a bit peculiar. RIP neighbors are interlinked with core neighbor structures (<struct/neighbor/) and use core neighbor notifications to ensure that RIP neighbors are timely removed. RIP neighbors are added based on received route notifications and removed based on core neighbor and RIP interface events. RIP neighbors are linked by RIP routes and use counter to track the number of associated routes, but when these RIP routes timeout, associated RIP neighbor is still alive (with zero counter). When RIP neighbor is removed but still has some associated routes, it is not freed, just changed to detached state (core neighbors and RIP ifaces are unlinked), then during the main timer cleanup phase the associated routes are removed and the <struct/rip_neighbor/ structure is finally freed. Supported standards: - RFC 1058 - RIPv1 - RFC 2453 - RIPv2 - RFC 2080 - RIPng - RFC 4822 - RIP cryptographic authentication <function><type>void</type> <funcdef>rip_announce_rte</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct rip_proto *</type> <param>p</param></tagp> RIP instance <tagp><type>struct rip_entry *</type> <param>en</param></tagp> related network </descrip> <funcsect>Description The function takes a list of incoming routes from <param/en/, prepare appropriate <struct/rte/ for the core and propagate it by <func/rte_update()/. </function> <function><type>void</type> <funcdef>rip_update_rte</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct rip_proto *</type> <param>p</param></tagp> RIP instance <tagp><type>ip_addr *</type> <param>prefix</param></tagp> network prefix <tagp><type>int</type> <param>pxlen</param></tagp> network prefix length <tagp><type>struct rip_rte *</type> <param>new</param></tagp> a <struct/rip_rte/ representing the new route </descrip> <funcsect>Description The function is called by the RIP packet processing code whenever it receives a reachable route. The appropriate routing table entry is found and the list of incoming routes is updated. Eventually, the change is also propagated to the core by <func/rip_announce_rte()/. Note that for unreachable routes, <func/rip_withdraw_rte()/ should be called instead of <func/rip_update_rte()/. </function> <function><type>void</type> <funcdef>rip_withdraw_rte</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct rip_proto *</type> <param>p</param></tagp> RIP instance <tagp><type>ip_addr *</type> <param>prefix</param></tagp> network prefix <tagp><type>int</type> <param>pxlen</param></tagp> network prefix length <tagp><type>struct rip_neighbor *</type> <param>from</param></tagp> a <struct/rip_neighbor/ propagating the withdraw </descrip> <funcsect>Description The function is called by the RIP packet processing code whenever it receives an unreachable route. The incoming route for given network from nbr <param/from/ is removed. Eventually, the change is also propagated by <func/rip_announce_rte()/. </function> <function><type>void</type> <funcdef>rip_timer</funcdef> (<type>timer *</type> <param>t</param>) -- RIP main timer hook <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>t</param></tagp> timer </descrip> <funcsect>Description The RIP main timer is responsible for routing table maintenance. Invalid or expired routes (<struct/rip_rte/) are removed and garbage collection of stale routing table entries (<struct/rip_entry/) is done. Changes are propagated to core tables, route reload is also done here. Note that garbage collection uses a maximal GC time, while interfaces maintain an illusion of per-interface GC times in <func/rip_send_response()/. Keeping incoming routes and the selected outgoing route are two independent functions, therefore after garbage collection some entries now considered invalid (RIP_ENTRY_DUMMY) still may have non-empty list of incoming routes, while some valid entries (representing an outgoing route) may have that list empty. The main timer is not scheduled periodically but it uses the time of the current next event and the minimal interval of any possible event to compute the time of the next run. </function> <function><type>void</type> <funcdef>rip_iface_timer</funcdef> (<type>timer *</type> <param>t</param>) -- RIP interface timer hook <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>t</param></tagp> timer </descrip> <funcsect>Description RIP interface timers are responsible for scheduling both regular and triggered updates. Fixed, delay-independent period is used for regular updates, while minimal separating interval is enforced for triggered updates. The function also ensures that a new update is not started when the old one is still running. </function> <function><type>void</type> <funcdef>rip_send_table</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct rip_proto *</type> <param>p</param></tagp> RIP instance <tagp><type>struct rip_iface *</type> <param>ifa</param></tagp> RIP interface <tagp><type>ip_addr</type> <param>addr</param></tagp> destination IP address <tagp><type>bird_clock_t</type> <param>changed</param></tagp> time limit for triggered updates </descrip> <funcsect>Description The function activates an update session and starts sending routing update packets (using <func/rip_send_response()/). The session may be finished during the call or may continue in <func/rip_tx_hook()/ until all appropriate routes are transmitted. Note that there may be at most one active update session per interface, the function will terminate the old active session before activating the new one. </function> <sect>Router Advertisements The RAdv protocol is implemented in two files: <tt>radv.c</tt> containing the interface with BIRD core and the protocol logic and <tt>packets.c</tt> handling low level protocol stuff (RX, TX and packet formats). The protocol does not export any routes. The RAdv is structured in the usual way - for each handled interface there is a structure <struct/radv_iface/ that contains a state related to that interface together with its resources (a socket, a timer). There is also a prepared RA stored in a TX buffer of the socket associated with an iface. These iface structures are created and removed according to iface events from BIRD core handled by <func/radv_if_notify()/ callback. The main logic of RAdv consists of two functions: <func/radv_iface_notify()/, which processes asynchronous events (specified by RA_EV_* codes), and <func/radv_timer()/, which triggers sending RAs and computes the next timeout. The RAdv protocol could receive routes (through <func/radv_import_control()/ and <func/radv_rt_notify()/), but only the configured trigger route is tracked (in <struct/active/ var). When a radv protocol is reconfigured, the connected routing table is examined (in <func/radv_check_active()/) to have proper <struct/active/ value in case of the specified trigger prefix was changed. Supported standards: - RFC 4861 - main RA standard - RFC 4191 - Default Router Preferences and More-Specific Routes - RFC 6106 - DNS extensions (RDDNS, DNSSL) <sect>Static The Static protocol is implemented in a straightforward way. It keeps two lists of static routes: one containing interface routes and one holding the remaining ones. Interface routes are inserted and removed according to interface events received from the core via the <func/if_notify()/ hook. Routes pointing to a neighboring router use a sticky node in the neighbor cache to be notified about gaining or losing the neighbor. Special routes like black holes or rejects are inserted all the time. Multipath routes are tricky. Because these routes depends on several neighbors we need to integrate that to the neighbor notification handling, we use dummy static_route nodes, one for each nexthop. Therefore, a multipath route consists of a master static_route node (of dest RTD_MULTIPATH), which specifies prefix and is used in most circumstances, and a list of dummy static_route nodes (of dest RTD_NONE), which stores info about nexthops and are connected to neighbor entries and neighbor notifications. Dummy nodes are chained using mp_next, they aren't in other_routes list, and abuse some fields (masklen, if_name) for other purposes. The only other thing worth mentioning is that when asked for reconfiguration, Static not only compares the two configurations, but it also calculates difference between the lists of static routes and it just inserts the newly added routes and removes the obsolete ones. <sect>Direct The Direct protocol works by converting all <func/ifa_notify()/ events it receives to <func/rte_update()/ calls for the corresponding network.  <chapt>System dependent parts <sect>Introduction We've tried to make BIRD as portable as possible, but unfortunately communication with the network stack differs from one OS to another, so we need at least some OS specific code. The good news is that this code is isolated in a small set of modules: <descrip> <tagp><tt/config.h/</tagp> is a header file with configuration information, definition of the standard set of types and so on. <tagp/Startup module/ controls BIRD startup. Common for a family of OS's (e.g., for all Unices). <tagp/Logging module/ manages the system logs. [per OS family] <tagp/IO module/ gives an implementation of sockets, timers and the global event queue. [per OS family] <tagp/KRT module/ implements the Kernel and Device protocols. This is the most arcane part of the system dependent stuff and some functions differ even between various releases of a single OS. </descrip> <sect>Logging The Logging module offers a simple set of functions for writing messages to system logs and to the debug output. Message classes used by this module are described in <tt>birdlib.h</tt> and also in the user's manual. <function><type>void</type> <funcdef>log_commit</funcdef> (<type>int</type> <param>class</param>, <type>buffer *</type> <param>buf</param>) -- commit a log message <funcsect>Arguments <descrip> <tagp><type>int</type> <param>class</param></tagp> message class information (<const/L_DEBUG/ to <const/L_BUG/, see <tt>lib/birdlib.h</tt>) <tagp><type>buffer *</type> <param>buf</param></tagp> message to write </descrip> <funcsect>Description This function writes a message prepared in the log buffer to the log file (as specified in the configuration). The log buffer is reset after that. The log message is a full line, <func/log_commit()/ terminates it. The message class is an integer, not a first char of a string like in <func/log()/, so it should be written like *L_INFO. </function> <function><type>void</type> <funcdef>log_msg</funcdef> (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- log a message <funcsect>Arguments <descrip> <tagp><type>const char *</type> <param>msg</param></tagp> printf-like formatting string with message class information prepended (<const/L_DEBUG/ to <const/L_BUG/, see <tt>lib/birdlib.h</tt>) <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function formats a message according to the format string <param/msg/ and writes it to the corresponding log file (as specified in the configuration). Please note that the message is automatically formatted as a full line, no need to include <tt>\n</tt> inside. It is essentially a sequence of <func/log_reset()/, <func/logn()/ and <func/log_commit()/. </function> <function><type>void</type> <funcdef>bug</funcdef> (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report an internal error <funcsect>Arguments <descrip> <tagp><type>const char *</type> <param>msg</param></tagp> a printf-like error message <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function logs an internal error and aborts execution of the program. </function> <function><type>void</type> <funcdef>die</funcdef> (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report a fatal error <funcsect>Arguments <descrip> <tagp><type>const char *</type> <param>msg</param></tagp> a printf-like error message <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function logs a fatal error and aborts execution of the program. </function> <function><type>void</type> <funcdef>debug</funcdef> (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- write to debug output <funcsect>Arguments <descrip> <tagp><type>const char *</type> <param>msg</param></tagp> a printf-like message <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function formats the message <param/msg/ and prints it out to the debugging output. No newline character is appended. </function> <sect>Kernel synchronization This system dependent module implements the Kernel and Device protocol, that is synchronization of interface lists and routing tables with the OS kernel. The whole kernel synchronization is a bit messy and touches some internals of the routing table engine, because routing table maintenance is a typical example of the proverbial compatibility between different Unices and we want to keep the overhead of our KRT business as low as possible and avoid maintaining a local routing table copy. The kernel syncer can work in three different modes (according to system config header): Either with a single routing table and single KRT protocol [traditional UNIX] or with many routing tables and separate KRT protocols for all of them or with many routing tables, but every scan including all tables, so we start separate KRT protocols which cooperate with each other [Linux]. In this case, we keep only a single scan timer. We use FIB node flags in the routing table to keep track of route synchronization status. We also attach temporary <struct/rte/'s to the routing table, but it cannot do any harm to the rest of BIRD since table synchronization is an atomic process. When starting up, we cheat by looking if there is another KRT instance to be initialized later and performing table scan only once for all the instances. The code uses OS-dependent parts for kernel updates and scans. These parts are in more specific sysdep directories (e.g. sysdep/linux) in functions krt_sys_* and kif_sys_* (and some others like <func/krt_replace_rte()/) and krt-sys.h header file. This is also used for platform specific protocol options and route attributes. There was also an old code that used traditional UNIX ioctls for these tasks. It was unmaintained and later removed. For reference, see sysdep/krt-* files in commit 396dfa9042305f62da1f56589c4b98fac57fc2f6 <chapt>Library functions <sect>IP addresses BIRD uses its own abstraction of IP address in order to share the same code for both IPv4 and IPv6. IP addresses are represented as entities of type <struct/ip_addr/ which are never to be treated as numbers and instead they must be manipulated using the following functions and macros. <function><type>char *</type> <funcdef>ip_scope_text</funcdef> (<type>uint</type> <param>scope</param>) -- get textual representation of address scope <funcsect>Arguments <descrip> <tagp><type>uint</type> <param>scope</param></tagp> scope (<const/SCOPE_xxx/) </descrip> <funcsect>Description Returns a pointer to a textual name of the scope given. </function> <function><type>int</type> <funcdef>ipa_equal</funcdef> (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compare two IP addresses for equality <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address <tagp><type>ip_addr</type> <param>y</param></tagp> IP address </descrip> <funcsect>Description <func/ipa_equal()/ returns 1 if <param/x/ and <param/y/ represent the same IP address, else 0. </function> <function><type>int</type> <funcdef>ipa_nonzero</funcdef> (<type>ip_addr</type> <param>x</param>) -- test if an IP address is defined <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address </descrip> <funcsect>Description ipa_nonzero returns 1 if <param/x/ is a defined IP address (not all bits are zero), else 0. The undefined all-zero address is reachable as a <tt>IPA_NONE</tt> macro. </function> <function><type>ip_addr</type> <funcdef>ipa_and</funcdef> (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise and of two IP addresses <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address <tagp><type>ip_addr</type> <param>y</param></tagp> IP address </descrip> <funcsect>Description This function returns a bitwise and of <param/x/ and <param/y/. It's primarily used for network masking. </function> <function><type>ip_addr</type> <funcdef>ipa_or</funcdef> (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise or of two IP addresses <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address <tagp><type>ip_addr</type> <param>y</param></tagp> IP address </descrip> <funcsect>Description This function returns a bitwise or of <param/x/ and <param/y/. </function> <function><type>ip_addr</type> <funcdef>ipa_xor</funcdef> (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise xor of two IP addresses <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address <tagp><type>ip_addr</type> <param>y</param></tagp> IP address </descrip> <funcsect>Description This function returns a bitwise xor of <param/x/ and <param/y/. </function> <function><type>ip_addr</type> <funcdef>ipa_not</funcdef> (<type>ip_addr</type> <param>x</param>) -- compute bitwise negation of two IP addresses <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address </descrip> <funcsect>Description This function returns a bitwise negation of <param/x/. </function> <function><type>ip_addr</type> <funcdef>ipa_mkmask</funcdef> (<type>int</type> <param>x</param>) -- create a netmask <funcsect>Arguments <descrip> <tagp><type>int</type> <param>x</param></tagp> prefix length </descrip> <funcsect>Description This function returns an <struct/ip_addr/ corresponding of a netmask of an address prefix of size <param/x/. </function> <function><type>int</type> <funcdef>ipa_masklen</funcdef> (<type>ip_addr</type> <param>x</param>) -- calculate netmask length <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address </descrip> <funcsect>Description This function checks whether <param/x/ represents a valid netmask and returns the size of the associate network prefix or -1 for invalid mask. </function> <function><type>int</type> <funcdef>ipa_hash</funcdef> (<type>ip_addr</type> <param>x</param>) -- hash IP addresses <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address </descrip> <funcsect>Description <func/ipa_hash()/ returns a 16-bit hash value of the IP address <param/x/. </function> <function><type>void</type> <funcdef>ipa_hton</funcdef> (<type>ip_addr</type> <param>x</param>) -- convert IP address to network order <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address </descrip> <funcsect>Description Converts the IP address <param/x/ to the network byte order. Beware, this is a macro and it alters the argument! </function> <function><type>void</type> <funcdef>ipa_ntoh</funcdef> (<type>ip_addr</type> <param>x</param>) -- convert IP address to host order <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address </descrip> <funcsect>Description Converts the IP address <param/x/ from the network byte order. Beware, this is a macro and it alters the argument! </function> <function><type>int</type> <funcdef>ipa_classify</funcdef> (<type>ip_addr</type> <param>x</param>) -- classify an IP address <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address </descrip> <funcsect>Description <func/ipa_classify()/ returns an address class of <param/x/, that is a bitwise or of address type (<const/IADDR_INVALID/, <const/IADDR_HOST/, <const/IADDR_BROADCAST/, <const/IADDR_MULTICAST/) with address scope (<const/SCOPE_HOST/ to <const/SCOPE_UNIVERSE/) or -1 (<const/IADDR_INVALID/) for an invalid address. </function> <function><type>ip4_addr</type> <funcdef>ip4_class_mask</funcdef> (<type>ip4_addr</type> <param>x</param>) -- guess netmask according to address class <funcsect>Arguments <descrip> <tagp><type>ip4_addr</type> <param>x</param></tagp> IPv4 address </descrip> <funcsect>Description This function (available in IPv4 version only) returns a network mask according to the address class of <param/x/. Although classful addressing is nowadays obsolete, there still live routing protocols transferring no prefix lengths nor netmasks and this function could be useful to them. </function> <function><type>u32</type> <funcdef>ipa_from_u32</funcdef> (<type>ip_addr</type> <param>x</param>) -- convert IPv4 address to an integer <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address </descrip> <funcsect>Description This function takes an IPv4 address and returns its numeric representation. </function> <function><type>ip_addr</type> <funcdef>ipa_to_u32</funcdef> (<type>u32</type> <param>x</param>) -- convert integer to IPv4 address <funcsect>Arguments <descrip> <tagp><type>u32</type> <param>x</param></tagp> a 32-bit integer </descrip> <funcsect>Description <func/ipa_to_u32()/ takes a numeric representation of an IPv4 address and converts it to the corresponding <struct/ip_addr/. </function> <function><type>int</type> <funcdef>ipa_compare</funcdef> (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compare two IP addresses for order <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>x</param></tagp> IP address <tagp><type>ip_addr</type> <param>y</param></tagp> IP address </descrip> <funcsect>Description The <func/ipa_compare()/ function takes two IP addresses and returns -1 if <param/x/ is less than <param/y/ in canonical ordering (lexicographical order of the bit strings), 1 if <param/x/ is greater than <param/y/ and 0 if they are the same. </function> <function><type>ip_addr</type> <funcdef>ipa_build6</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>u32</type> <param>a1</param></tagp> part #1 <tagp><type>u32</type> <param>a2</param></tagp> part #2 <tagp><type>u32</type> <param>a3</param></tagp> part #3 <tagp><type>u32</type> <param>a4</param></tagp> part #4 </descrip> <funcsect>Description <func/ipa_build()/ takes <param/a1/ to <param/a4/ and assembles them to a single IPv6 address. It's used for example when a protocol wants to bind its socket to a hard-wired multicast address. </function> <function><type>char *</type> <funcdef>ip_ntop</funcdef> (<type>ip_addr</type> <param>a</param>, <type>char *</type> <param>buf</param>) -- convert IP address to textual representation <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>a</param></tagp> IP address <tagp><type>char *</type> <param>buf</param></tagp> buffer of size at least <const/STD_ADDRESS_P_LENGTH/ </descrip> <funcsect>Description This function takes an IP address and creates its textual representation for presenting to the user. </function> <function><type>char *</type> <funcdef>ip_ntox</funcdef> (<type>ip_addr</type> <param>a</param>, <type>char *</type> <param>buf</param>) -- convert IP address to hexadecimal representation <funcsect>Arguments <descrip> <tagp><type>ip_addr</type> <param>a</param></tagp> IP address <tagp><type>char *</type> <param>buf</param></tagp> buffer of size at least <const/STD_ADDRESS_P_LENGTH/ </descrip> <funcsect>Description This function takes an IP address and creates its hexadecimal textual representation. Primary use: debugging dumps. </function> <function><type>int</type> <funcdef>ip_pton</funcdef> (<type>char *</type> <param>a</param>, <type>ip_addr *</type> <param>o</param>) -- parse textual representation of IP address <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>a</param></tagp> textual representation <tagp><type>ip_addr *</type> <param>o</param></tagp> where to put the resulting address </descrip> <funcsect>Description This function parses a textual IP address representation and stores the decoded address to a variable pointed to by <param/o/. Returns 0 if a parse error has occurred, else 0. </function> <sect>Linked lists The BIRD library provides a set of functions for operating on linked lists. The lists are internally represented as standard doubly linked lists with synthetic head and tail which makes all the basic operations run in constant time and contain no extra end-of-list checks. Each list is described by a <struct/list/ structure, nodes can have any format as long as they start with a <struct/node/ structure. If you want your nodes to belong to multiple lists at once, you can embed multiple <struct/node/ structures in them and use the <func/SKIP_BACK()/ macro to calculate a pointer to the start of the structure from a <struct/node/ pointer, but beware of obscurity. There also exist safe linked lists (<struct/slist/, <struct/snode/ and all functions being prefixed with <tt>s_</tt>) which support asynchronous walking very similar to that used in the <struct/fib/ structure. <function><type>LIST_INLINE void</type> <funcdef>add_tail</funcdef> (<type>list *</type> <param>l</param>, <type>node *</type> <param>n</param>) -- append a node to a list <funcsect>Arguments <descrip> <tagp><type>list *</type> <param>l</param></tagp> linked list <tagp><type>node *</type> <param>n</param></tagp> list node </descrip> <funcsect>Description <func/add_tail()/ takes a node <param/n/ and appends it at the end of the list <param/l/. </function> <function><type>LIST_INLINE void</type> <funcdef>add_head</funcdef> (<type>list *</type> <param>l</param>, <type>node *</type> <param>n</param>) -- prepend a node to a list <funcsect>Arguments <descrip> <tagp><type>list *</type> <param>l</param></tagp> linked list <tagp><type>node *</type> <param>n</param></tagp> list node </descrip> <funcsect>Description <func/add_head()/ takes a node <param/n/ and prepends it at the start of the list <param/l/. </function> <function><type>LIST_INLINE void</type> <funcdef>insert_node</funcdef> (<type>node *</type> <param>n</param>, <type>node *</type> <param>after</param>) -- insert a node to a list <funcsect>Arguments <descrip> <tagp><type>node *</type> <param>n</param></tagp> a new list node <tagp><type>node *</type> <param>after</param></tagp> a node of a list </descrip> <funcsect>Description Inserts a node <param/n/ to a linked list after an already inserted node <param/after/. </function> <function><type>LIST_INLINE void</type> <funcdef>rem_node</funcdef> (<type>node *</type> <param>n</param>) -- remove a node from a list <funcsect>Arguments <descrip> <tagp><type>node *</type> <param>n</param></tagp> node to be removed </descrip> <funcsect>Description Removes a node <param/n/ from the list it's linked in. Afterwards, node <param/n/ is cleared. </function> <function><type>LIST_INLINE void</type> <funcdef>replace_node</funcdef> (<type>node *</type> <param>old</param>, <type>node *</type> <param>new</param>) -- replace a node in a list with another one <funcsect>Arguments <descrip> <tagp><type>node *</type> <param>old</param></tagp> node to be removed <tagp><type>node *</type> <param>new</param></tagp> node to be inserted </descrip> <funcsect>Description Replaces node <param/old/ in the list it's linked in with node <param/new/. Node <param/old/ may be a copy of the original node, which is not accessed through the list. The function could be called with <param/old/ == <param/new/, which just fixes neighbors' pointers in the case that the node was reallocated. </function> <function><type>LIST_INLINE void</type> <funcdef>init_list</funcdef> (<type>list *</type> <param>l</param>) -- create an empty list <funcsect>Arguments <descrip> <tagp><type>list *</type> <param>l</param></tagp> list </descrip> <funcsect>Description <func/init_list()/ takes a <struct/list/ structure and initializes its fields, so that it represents an empty list. </function> <function><type>LIST_INLINE void</type> <funcdef>add_tail_list</funcdef> (<type>list *</type> <param>to</param>, <type>list *</type> <param>l</param>) -- concatenate two lists <funcsect>Arguments <descrip> <tagp><type>list *</type> <param>to</param></tagp> destination list <tagp><type>list *</type> <param>l</param></tagp> source list </descrip> <funcsect>Description This function appends all elements of the list <param/l/ to the list <param/to/ in constant time. </function> <sect>Miscellaneous functions. <function><type>int</type> <funcdef>ipsum_verify</funcdef> (<type>void *</type> <param>frag</param>, <type>uint</type> <param>len</param>, <type>...</type> <param>...</param>) -- verify an IP checksum <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>frag</param></tagp> first packet fragment <tagp><type>uint</type> <param>len</param></tagp> length in bytes <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function verifies whether a given fragmented packet has correct one's complement checksum as used by the IP protocol. It uses all the clever tricks described in RFC 1071 to speed up checksum calculation as much as possible. <funcsect>Result 1 if the checksum is correct, 0 else. </function> <function><type>u16</type> <funcdef>ipsum_calculate</funcdef> (<type>void *</type> <param>frag</param>, <type>uint</type> <param>len</param>, <type>...</type> <param>...</param>) -- compute an IP checksum <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>frag</param></tagp> first packet fragment <tagp><type>uint</type> <param>len</param></tagp> length in bytes <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function calculates a one's complement checksum of a given fragmented packet. It uses all the clever tricks described in RFC 1071 to speed up checksum calculation as much as possible. </function> <function><type>u32</type> <funcdef>u32_mkmask</funcdef> (<type>uint</type> <param>n</param>) -- create a bit mask <funcsect>Arguments <descrip> <tagp><type>uint</type> <param>n</param></tagp> number of bits </descrip> <funcsect>Description <func/u32_mkmask()/ returns an unsigned 32-bit integer which binary representation consists of <param/n/ ones followed by zeroes. </function> <function><type>int</type> <funcdef>u32_masklen</funcdef> (<type>u32</type> <param>x</param>) -- calculate length of a bit mask <funcsect>Arguments <descrip> <tagp><type>u32</type> <param>x</param></tagp> bit mask </descrip> <funcsect>Description This function checks whether the given integer <param/x/ represents a valid bit mask (binary representation contains first ones, then zeroes) and returns the number of ones or -1 if the mask is invalid. </function> <function><type>u32</type> <funcdef>u32_log2</funcdef> (<type>u32</type> <param>v</param>) -- compute a binary logarithm. <funcsect>Arguments <descrip> <tagp><type>u32</type> <param>v</param></tagp> number </descrip> <funcsect>Description This function computes a integral part of binary logarithm of given integer <param/v/ and returns it. The computed value is also an index of the most significant non-zero bit position. </function> <function><type>int</type> <funcdef>patmatch</funcdef> (<type>byte *</type> <param>p</param>, <type>byte *</type> <param>s</param>) -- match shell-like patterns <funcsect>Arguments <descrip> <tagp><type>byte *</type> <param>p</param></tagp> pattern <tagp><type>byte *</type> <param>s</param></tagp> string </descrip> <funcsect>Description <func/patmatch()/ returns whether given string <param/s/ matches the given shell-like pattern <param/p/. The patterns consist of characters (which are matched literally), question marks which match any single character, asterisks which match any (possibly empty) string of characters and backslashes which are used to escape any special characters and force them to be treated literally. The matching process is not optimized with respect to time, so please avoid using this function for complex patterns. </function> <function><type>int</type> <funcdef>bvsnprintf</funcdef> (<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()/ <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>buf</param></tagp> destination buffer <tagp><type>int</type> <param>size</param></tagp> size of the buffer <tagp><type>const char *</type> <param>fmt</param></tagp> format string <tagp><type>va_list</type> <param>args</param></tagp> a list of arguments to be formatted </descrip> <funcsect>Description This functions acts like ordinary <func/sprintf()/ except that it checks available space to avoid buffer overflows and it allows some more <funcsect>format specifiers <tt><const/I/</tt> for formatting of IP addresses (any non-zero width is automatically replaced by standard IP address width which depends on whether we use IPv4 or IPv6; <tt>%#I</tt> gives hexadecimal format), <tt><const/R/</tt> for Router / Network ID (u32 value printed as IPv4 address) <tt><const/lR/</tt> for 64bit Router / Network ID (u64 value printed as eight :-separated octets) and <tt><const/m/</tt> resp. <tt><const/M/</tt> for error messages (uses <func/strerror()/ to translate <param/errno/ code to message text). On the other hand, it doesn't support floating point numbers. <funcsect>Result number of characters of the output string or -1 if the buffer space was insufficient. </function> <function><type>int</type> <funcdef>bvsprintf</funcdef> (<type>char *</type> <param>buf</param>, <type>const char *</type> <param>fmt</param>, <type>va_list</type> <param>args</param>) -- BIRD's <func/vsprintf()/ <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>buf</param></tagp> buffer <tagp><type>const char *</type> <param>fmt</param></tagp> format string <tagp><type>va_list</type> <param>args</param></tagp> a list of arguments to be formatted </descrip> <funcsect>Description This function is equivalent to <func/bvsnprintf()/ with an infinite buffer size. Please use carefully only when you are absolutely sure the buffer won't overflow. </function> <function><type>int</type> <funcdef>bsprintf</funcdef> (<type>char *</type> <param>buf</param>, <type>const char *</type> <param>fmt</param>, <type>...</type> <param>...</param>) -- BIRD's <func/sprintf()/ <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>buf</param></tagp> buffer <tagp><type>const char *</type> <param>fmt</param></tagp> format string <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function is equivalent to <func/bvsnprintf()/ with an infinite buffer size and variable arguments instead of a <struct/va_list/. Please use carefully only when you are absolutely sure the buffer won't overflow. </function> <function><type>int</type> <funcdef>bsnprintf</funcdef> (<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()/ <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>buf</param></tagp> buffer <tagp><type>int</type> <param>size</param></tagp> buffer size <tagp><type>const char *</type> <param>fmt</param></tagp> format string <tagp><type>...</type> <param>...</param></tagp> variable arguments </descrip> <funcsect>Description This function is equivalent to <func/bsnprintf()/ with variable arguments instead of a <struct/va_list/. </function> <function><type>void *</type> <funcdef>xmalloc</funcdef> (<type>uint</type> <param>size</param>) -- malloc with checking <funcsect>Arguments <descrip> <tagp><type>uint</type> <param>size</param></tagp> block size </descrip> <funcsect>Description This function is equivalent to <func/malloc()/ except that in case of failure it calls <func/die()/ to quit the program instead of returning a <const/NULL/ pointer. Wherever possible, please use the memory resources instead. </function> <function><type>void *</type> <funcdef>xrealloc</funcdef> (<type>void *</type> <param>ptr</param>, <type>uint</type> <param>size</param>) -- realloc with checking <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>ptr</param></tagp> original memory block <tagp><type>uint</type> <param>size</param></tagp> block size </descrip> <funcsect>Description This function is equivalent to <func/realloc()/ except that in case of failure it calls <func/die()/ to quit the program instead of returning a <const/NULL/ pointer. Wherever possible, please use the memory resources instead. </function> <sect>Message authentication codes MAC algorithms are simple cryptographic tools for message authentication. They use shared a secret key a and message text to generate authentication code, which is then passed with the message to the other side, where the code is verified. There are multiple families of MAC algorithms based on different cryptographic primitives, BIRD implements two MAC families which use hash functions. The first family is simply a cryptographic hash camouflaged as MAC algorithm. Originally supposed to be (m|k)-hash (message is concatenated with key, and that is hashed), but later it turned out that a raw hash is more practical. This is used for cryptographic authentication in OSPFv2, RIP and BFD. The second family is the standard HMAC (RFC 2104), using inner and outer hash to process key and message. HMAC (with SHA) is used in advanced OSPF and RIP authentication (RFC 5709, RFC 4822). <function><type>void</type> <funcdef>mac_init</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct mac_context *</type> <param>ctx</param></tagp> context to initialize <tagp><type>uint</type> <param>id</param></tagp> MAC algorithm ID <tagp><type>const byte *</type> <param>key</param></tagp> MAC key <tagp><type>uint</type> <param>keylen</param></tagp> MAC key length </descrip> <funcsect>Description Initialize MAC context <param/ctx/ for algorithm <param/id/ (e.g., <const/ALG_HMAC_SHA1/), with key <param/key/ of length <param/keylen/. After that, message data could be added using <func/mac_update()/ function. </function> <function><type>void</type> <funcdef>mac_update</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>struct mac_context *</type> <param>ctx</param></tagp> MAC context <tagp><type>const byte *</type> <param>data</param></tagp> data to add <tagp><type>uint</type> <param>datalen</param></tagp> length of data </descrip> <funcsect>Description Push another <param/datalen/ bytes of data pointed to by <param/data/ into the MAC algorithm currently in <param/ctx/. Can be called multiple times for the same MAC context. It has the same effect as concatenating all the data together and passing them at once. </function> <function><type>byte *</type> <funcdef>mac_final</funcdef> (<type>struct mac_context *</type> <param>ctx</param>) -- finalize MAC algorithm <funcsect>Arguments <descrip> <tagp><type>struct mac_context *</type> <param>ctx</param></tagp> MAC context </descrip> <funcsect>Description Finish MAC computation and return a pointer to the result. No more <param/mac_update/() calls could be done, but the context may be reinitialized later. Note that the returned pointer points into data in the <param/ctx/ context. If it ceases to exist, the pointer becomes invalid. </function> <function><type>void</type> <funcdef>mac_cleanup</funcdef> (<type>struct mac_context *</type> <param>ctx</param>) -- cleanup MAC context <funcsect>Arguments <descrip> <tagp><type>struct mac_context *</type> <param>ctx</param></tagp> MAC context </descrip> <funcsect>Description Cleanup MAC context after computation (by filling with zeros). Not strictly necessary, just to erase sensitive data from stack. This also invalidates the pointer returned by <param/mac_final/(). </function> <function><type>void</type> <funcdef>mac_fill</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>uint</type> <param>id</param></tagp> MAC algorithm ID <tagp><type>const byte *</type> <param>key</param></tagp> secret key <tagp><type>uint</type> <param>keylen</param></tagp> key length <tagp><type>const byte *</type> <param>data</param></tagp> message data <tagp><type>uint</type> <param>datalen</param></tagp> message length <tagp><type>byte *</type> <param>mac</param></tagp> place to fill MAC </descrip> <funcsect>Description Compute MAC for specified key <param/key/ and message <param/data/ using algorithm <param/id/ and copy it to buffer <param/mac/. <func/mac_fill()/ is a shortcut function doing all usual steps for transmitted messages. </function> <function><type>int</type> <funcdef>mac_verify</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>uint</type> <param>id</param></tagp> MAC algorithm ID <tagp><type>const byte *</type> <param>key</param></tagp> secret key <tagp><type>uint</type> <param>keylen</param></tagp> key length <tagp><type>const byte *</type> <param>data</param></tagp> message data <tagp><type>uint</type> <param>datalen</param></tagp> message length <tagp><type>const byte *</type> <param>mac</param></tagp> received MAC </descrip> <funcsect>Description Compute MAC for specified key <param/key/ and message <param/data/ using algorithm <param/id/ and compare it with received <param/mac/, return whether they are the same. <func/mac_verify()/ is a shortcut function doing all usual steps for received messages. </function>  <chapt>Resources <sect>Introduction Most large software projects implemented in classical procedural programming languages usually end up with lots of code taking care of resource allocation and deallocation. Bugs in such code are often very difficult to find, because they cause only `resource leakage', that is keeping a lot of memory and other resources which nobody references to. We've tried to solve this problem by employing a resource tracking system which keeps track of all the resources allocated by all the modules of BIRD, deallocates everything automatically when a module shuts down and it is able to print out the list of resources and the corresponding modules they are allocated by. Each allocated resource (from now we'll speak about allocated resources only) is represented by a structure starting with a standard header (struct <struct/resource/) consisting of a list node (resources are often linked to various lists) and a pointer to <struct/resclass/ -- a resource class structure pointing to functions implementing generic resource operations (such as freeing of the resource) for the particular resource type. There exist the following types of resources: <itemize> <item><it/Resource pools/ (<struct/pool/) <item><it/Memory blocks/ <item><it/Linear memory pools/ (<struct/linpool/) <item><it/Slabs/ (<struct/slab/) <item><it/Events/ (<struct/event/) <item><it/Timers/ (<struct/timer/) <item><it/Sockets/ (<struct/socket/) </itemize> <sect>Resource pools Resource pools (<struct/pool/) are just containers holding a list of other resources. Freeing a pool causes all the listed resources to be freed as well. Each existing <struct/resource/ is linked to some pool except for a root pool which isn't linked anywhere, so all the resources form a tree structure with internal nodes corresponding to pools and leaves being the other resources. Example: Almost all modules of BIRD have their private pool which is freed upon shutdown of the module. <function><type>pool *</type> <funcdef>rp_new</funcdef> (<type>pool *</type> <param>p</param>, <type>char *</type> <param>name</param>) -- create a resource pool <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> parent pool <tagp><type>char *</type> <param>name</param></tagp> pool name (to be included in debugging dumps) </descrip> <funcsect>Description <func/rp_new()/ creates a new resource pool inside the specified parent pool. </function> <function><type>void</type> <funcdef>rmove</funcdef> (<type>void *</type> <param>res</param>, <type>pool *</type> <param>p</param>) -- move a resource <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>res</param></tagp> resource <tagp><type>pool *</type> <param>p</param></tagp> pool to move the resource to </descrip> <funcsect>Description <func/rmove()/ moves a resource from one pool to another. </function> <function><type>void</type> <funcdef>rfree</funcdef> (<type>void *</type> <param>res</param>) -- free a resource <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>res</param></tagp> resource </descrip> <funcsect>Description <func/rfree()/ frees the given resource and all information associated with it. In case it's a resource pool, it also frees all the objects living inside the pool. It works by calling a class-specific freeing function. </function> <function><type>void</type> <funcdef>rdump</funcdef> (<type>void *</type> <param>res</param>) -- dump a resource <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>res</param></tagp> resource </descrip> <funcsect>Description This function prints out all available information about the given resource to the debugging output. It works by calling a class-specific dump function. </function> <function><type>void *</type> <funcdef>ralloc</funcdef> (<type>pool *</type> <param>p</param>, <type>struct resclass *</type> <param>c</param>) -- create a resource <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> pool to create the resource in <tagp><type>struct resclass *</type> <param>c</param></tagp> class of the new resource </descrip> <funcsect>Description This function is called by the resource classes to create a new resource of the specified class and link it to the given pool. Allocated memory is zeroed. Size of the resource structure is taken from the <param/size/ field of the <struct/resclass/. </function> <function><type>void</type> <funcdef>rlookup</funcdef> (<type>unsigned long</type> <param>a</param>) -- look up a memory location <funcsect>Arguments <descrip> <tagp><type>unsigned long</type> <param>a</param></tagp> memory address </descrip> <funcsect>Description This function examines all existing resources to see whether the address <param/a/ is inside any resource. It's used for debugging purposes only. It works by calling a class-specific lookup function for each resource. </function> <function><type>void</type> <funcdef>resource_init</funcdef> (<param>void</param>) -- initialize the resource manager <funcsect>Description This function is called during BIRD startup. It initializes all data structures of the resource manager and creates the root pool. </function> <sect>Memory blocks Memory blocks are pieces of contiguous allocated memory. They are a bit non-standard since they are represented not by a pointer to <struct/resource/, but by a void pointer to the start of data of the memory block. All memory block functions know how to locate the header given the data pointer. Example: All "unique" data structures such as hash tables are allocated as memory blocks. <function><type>void *</type> <funcdef>mb_alloc</funcdef> (<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) -- allocate a memory block <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> pool <tagp><type>unsigned</type> <param>size</param></tagp> size of the block </descrip> <funcsect>Description <func/mb_alloc()/ allocates memory of a given size and creates a memory block resource representing this memory chunk in the pool <param/p/. Please note that <func/mb_alloc()/ returns a pointer to the memory chunk, not to the resource, hence you have to free it using <func/mb_free()/, not <func/rfree()/. </function> <function><type>void *</type> <funcdef>mb_allocz</funcdef> (<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) -- allocate and clear a memory block <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> pool <tagp><type>unsigned</type> <param>size</param></tagp> size of the block </descrip> <funcsect>Description <func/mb_allocz()/ allocates memory of a given size, initializes it to zeroes and creates a memory block resource representing this memory chunk in the pool <param/p/. Please note that <func/mb_allocz()/ returns a pointer to the memory chunk, not to the resource, hence you have to free it using <func/mb_free()/, not <func/rfree()/. </function> <function><type>void *</type> <funcdef>mb_realloc</funcdef> (<type>void *</type> <param>m</param>, <type>unsigned</type> <param>size</param>) -- reallocate a memory block <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>m</param></tagp> memory block <tagp><type>unsigned</type> <param>size</param></tagp> new size of the block </descrip> <funcsect>Description <func/mb_realloc()/ changes the size of the memory block <param/m/ to a given size. The contents will be unchanged to the minimum of the old and new sizes; newly allocated memory will be uninitialized. Contrary to <func/realloc()/ behavior, <param/m/ must be non-NULL, because the resource pool is inherited from it. Like <func/mb_alloc()/, <func/mb_realloc()/ also returns a pointer to the memory chunk, not to the resource, hence you have to free it using <func/mb_free()/, not <func/rfree()/. </function> <function><type>void</type> <funcdef>mb_free</funcdef> (<type>void *</type> <param>m</param>) -- free a memory block <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>m</param></tagp> memory block </descrip> <funcsect>Description <func/mb_free()/ frees all memory associated with the block <param/m/. </function> <sect>Linear memory pools Linear memory pools are collections of memory blocks which support very fast allocation of new blocks, but are able to free only the whole collection at once. Example: Each configuration is described by a complex system of structures, linked lists and function trees which are all allocated from a single linear pool, thus they can be freed at once when the configuration is no longer used. <function><type>linpool *</type> <funcdef>lp_new</funcdef> (<type>pool *</type> <param>p</param>, <type>uint</type> <param>blk</param>) -- create a new linear memory pool <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> pool <tagp><type>uint</type> <param>blk</param></tagp> block size </descrip> <funcsect>Description <func/lp_new()/ creates a new linear memory pool resource inside the pool <param/p/. The linear pool consists of a list of memory chunks of size at least <param/blk/. </function> <function><type>void *</type> <funcdef>lp_alloc</funcdef> (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate memory from a <struct/linpool/ <funcsect>Arguments <descrip> <tagp><type>linpool *</type> <param>m</param></tagp> linear memory pool <tagp><type>uint</type> <param>size</param></tagp> amount of memory </descrip> <funcsect>Description <func/lp_alloc()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/ and it returns a pointer to the allocated memory. It works by trying to find free space in the last memory chunk associated with the <struct/linpool/ and creating a new chunk of the standard size (as specified during <func/lp_new()/) if the free space is too small to satisfy the allocation. If <param/size/ is too large to fit in a standard size chunk, an "overflow" chunk is created for it instead. </function> <function><type>void *</type> <funcdef>lp_allocu</funcdef> (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate unaligned memory from a <struct/linpool/ <funcsect>Arguments <descrip> <tagp><type>linpool *</type> <param>m</param></tagp> linear memory pool <tagp><type>uint</type> <param>size</param></tagp> amount of memory </descrip> <funcsect>Description <func/lp_allocu()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/ and it returns a pointer to the allocated memory. It doesn't attempt to align the memory block, giving a very efficient way how to allocate strings without any space overhead. </function> <function><type>void *</type> <funcdef>lp_allocz</funcdef> (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate cleared memory from a <struct/linpool/ <funcsect>Arguments <descrip> <tagp><type>linpool *</type> <param>m</param></tagp> linear memory pool <tagp><type>uint</type> <param>size</param></tagp> amount of memory </descrip> <funcsect>Description This function is identical to <func/lp_alloc()/ except that it clears the allocated memory block. </function> <function><type>void</type> <funcdef>lp_flush</funcdef> (<type>linpool *</type> <param>m</param>) -- flush a linear memory pool <funcsect>Arguments <descrip> <tagp><type>linpool *</type> <param>m</param></tagp> linear memory pool </descrip> <funcsect>Description This function frees the whole contents of the given <struct/linpool/ <param/m/, but leaves the pool itself. </function> <sect>Slabs Slabs are collections of memory blocks of a fixed size. They support very fast allocation and freeing of such blocks, prevent memory fragmentation and optimize L2 cache usage. Slabs have been invented by Jeff Bonwick and published in USENIX proceedings as `The Slab Allocator: An Object-Caching Kernel Memory Allocator'. Our implementation follows this article except that we don't use constructors and destructors. When the <tt>DEBUGGING</tt> switch is turned on, we automatically fill all newly allocated and freed blocks with a special pattern to make detection of use of uninitialized or already freed memory easier. Example: Nodes of a FIB are allocated from a per-FIB Slab. <function><type>slab *</type> <funcdef>sl_new</funcdef> (<type>pool *</type> <param>p</param>, <type>uint</type> <param>size</param>) -- create a new Slab <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> resource pool <tagp><type>uint</type> <param>size</param></tagp> block size </descrip> <funcsect>Description This function creates a new Slab resource from which objects of size <param/size/ can be allocated. </function> <function><type>void *</type> <funcdef>sl_alloc</funcdef> (<type>slab *</type> <param>s</param>) -- allocate an object from Slab <funcsect>Arguments <descrip> <tagp><type>slab *</type> <param>s</param></tagp> slab </descrip> <funcsect>Description <func/sl_alloc()/ allocates space for a single object from the Slab and returns a pointer to the object. </function> <function><type>void</type> <funcdef>sl_free</funcdef> (<type>slab *</type> <param>s</param>, <type>void *</type> <param>oo</param>) -- return a free object back to a Slab <funcsect>Arguments <descrip> <tagp><type>slab *</type> <param>s</param></tagp> slab <tagp><type>void *</type> <param>oo</param></tagp> object returned by <func/sl_alloc()/ </descrip> <funcsect>Description This function frees memory associated with the object <param/oo/ and returns it back to the Slab <param/s/. </function> <sect>Events Events are there to keep track of deferred execution. Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller parts, so that no module can monopolize the CPU. To split such a task, just create an <struct/event/ resource, point it to the function you want to have called and call <func/ev_schedule()/ to ask the core to run the event when nothing more important requires attention. You can also define your own event lists (the <struct/event_list/ structure), enqueue your events in them and explicitly ask to run them. <function><type>event *</type> <funcdef>ev_new</funcdef> (<type>pool *</type> <param>p</param>) -- create a new event <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> resource pool </descrip> <funcsect>Description This function creates a new event resource. To use it, you need to fill the structure fields and call <func/ev_schedule()/. </function> <function><type>void</type> <funcdef>ev_run</funcdef> (<type>event *</type> <param>e</param>) -- run an event <funcsect>Arguments <descrip> <tagp><type>event *</type> <param>e</param></tagp> an event </descrip> <funcsect>Description This function explicitly runs the event <param/e/ (calls its hook function) and removes it from an event list if it's linked to any. From the hook function, you can call <func/ev_enqueue()/ or <func/ev_schedule()/ to re-add the event. </function> <function><type>void</type> <funcdef>ev_enqueue</funcdef> (<type>event_list *</type> <param>l</param>, <type>event *</type> <param>e</param>) -- enqueue an event <funcsect>Arguments <descrip> <tagp><type>event_list *</type> <param>l</param></tagp> an event list <tagp><type>event *</type> <param>e</param></tagp> an event </descrip> <funcsect>Description <func/ev_enqueue()/ stores the event <param/e/ to the specified event list <param/l/ which can be run by calling <func/ev_run_list()/. </function> <function><type>void</type> <funcdef>ev_schedule</funcdef> (<type>event *</type> <param>e</param>) -- schedule an event <funcsect>Arguments <descrip> <tagp><type>event *</type> <param>e</param></tagp> an event </descrip> <funcsect>Description This function schedules an event by enqueueing it to a system-wide event list which is run by the platform dependent code whenever appropriate. </function> <function><type>int</type> <funcdef>ev_run_list</funcdef> (<type>event_list *</type> <param>l</param>) -- run an event list <funcsect>Arguments <descrip> <tagp><type>event_list *</type> <param>l</param></tagp> an event list </descrip> <funcsect>Description This function calls <func/ev_run()/ for all events enqueued in the list <param/l/. </function> <sect>Timers Timers are resources which represent a wish of a module to call a function at the specified time. The platform dependent code doesn't guarantee exact timing, only that a timer function won't be called before the requested time. In BIRD, time is represented by values of the <struct/bird_clock_t/ type which are integral numbers interpreted as a relative number of seconds since some fixed time point in past. The current time can be read from variable <param/now/ with reasonable accuracy and is monotonic. There is also a current 'absolute' time in variable <param/now_real/ reported by OS. Each timer is described by a <struct/timer/ structure containing a pointer to the handler function (<param/hook/), data private to this function (<param/data/), time the function should be called at (<param/expires/, 0 for inactive timers), for the other fields see <tt>timer.h</tt>. <function><type>timer *</type> <funcdef>tm_new</funcdef> (<type>pool *</type> <param>p</param>) -- create a timer <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> pool </descrip> <funcsect>Description This function creates a new timer resource and returns a pointer to it. To use the timer, you need to fill in the structure fields and call <func/tm_start()/ to start timing. </function> <function><type>void</type> <funcdef>tm_start</funcdef> (<type>timer *</type> <param>t</param>, <type>unsigned</type> <param>after</param>) -- start a timer <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>t</param></tagp> timer <tagp><type>unsigned</type> <param>after</param></tagp> number of seconds the timer should be run after </descrip> <funcsect>Description This function schedules the hook function of the timer to be called after <param/after/ seconds. If the timer has been already started, it's <param/expire/ time is replaced by the new value. You can have set the <param/randomize/ field of <param/t/, the timeout will be increased by a random number of seconds chosen uniformly from range 0 .. <param/randomize/. You can call <func/tm_start()/ from the handler function of the timer to request another run of the timer. Also, you can set the <param/recurrent/ field to have the timer re-added automatically with the same timeout. </function> <function><type>void</type> <funcdef>tm_stop</funcdef> (<type>timer *</type> <param>t</param>) -- stop a timer <funcsect>Arguments <descrip> <tagp><type>timer *</type> <param>t</param></tagp> timer </descrip> <funcsect>Description This function stops a timer. If the timer is already stopped, nothing happens. </function> <function><type>bird_clock_t</type> <funcdef>tm_parse_datetime</funcdef> (<type>char *</type> <param>x</param>) -- parse a date and time <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>x</param></tagp> datetime string </descrip> <funcsect>Description <func/tm_parse_datetime()/ takes a textual representation of a date and time (dd-mm-yyyy hh:mm:ss) and converts it to the corresponding value of type <struct/bird_clock_t/. </function> <function><type>bird_clock_t</type> <funcdef>tm_parse_date</funcdef> (<type>char *</type> <param>x</param>) -- parse a date <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>x</param></tagp> date string </descrip> <funcsect>Description <func/tm_parse_date()/ takes a textual representation of a date (dd-mm-yyyy) and converts it to the corresponding value of type <struct/bird_clock_t/. </function> <function><type>void</type> <funcdef>tm_format_datetime</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>char *</type> <param>x</param></tagp> destination buffer of size <const/TM_DATETIME_BUFFER_SIZE/ <tagp><type>struct timeformat *</type> <param>fmt_spec</param></tagp> specification of resulting textual representation of the time <tagp><type>bird_clock_t</type> <param>t</param></tagp> time </descrip> <funcsect>Description This function formats the given relative time value <param/t/ to a textual date/time representation (dd-mm-yyyy hh:mm:ss) in real time. </function> <sect>Sockets Socket resources represent network connections. Their data structure (<struct/socket/) contains a lot of fields defining the exact type of the socket, the local and remote addresses and ports, pointers to socket buffers and finally pointers to hook functions to be called when new data have arrived to the receive buffer (<param/rx_hook/), when the contents of the transmit buffer have been transmitted (<param/tx_hook/) and when an error or connection close occurs (<param/err_hook/). Freeing of sockets from inside socket hooks is perfectly safe. <function><type>int</type> <funcdef>sk_setup_multicast</funcdef> (<type>sock *</type> <param>s</param>) -- enable multicast for given socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket </descrip> <funcsect>Description Prepare transmission of multicast packets for given datagram socket. The socket must have defined <param/iface/. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>int</type> <funcdef>sk_join_group</funcdef> (<type>sock *</type> <param>s</param>, <type>ip_addr</type> <param>maddr</param>) -- join multicast group for given socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket <tagp><type>ip_addr</type> <param>maddr</param></tagp> multicast address </descrip> <funcsect>Description Join multicast group for given datagram socket and associated interface. The socket must have defined <param/iface/. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>int</type> <funcdef>sk_leave_group</funcdef> (<type>sock *</type> <param>s</param>, <type>ip_addr</type> <param>maddr</param>) -- leave multicast group for given socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket <tagp><type>ip_addr</type> <param>maddr</param></tagp> multicast address </descrip> <funcsect>Description Leave multicast group for given datagram socket and associated interface. The socket must have defined <param/iface/. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>int</type> <funcdef>sk_setup_broadcast</funcdef> (<type>sock *</type> <param>s</param>) -- enable broadcast for given socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket </descrip> <funcsect>Description Allow reception and transmission of broadcast packets for given datagram socket. The socket must have defined <param/iface/. For transmission, packets should be send to <param/brd/ address of <param/iface/. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>int</type> <funcdef>sk_set_ttl</funcdef> (<type>sock *</type> <param>s</param>, <type>int</type> <param>ttl</param>) -- set transmit TTL for given socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket <tagp><type>int</type> <param>ttl</param></tagp> TTL value </descrip> <funcsect>Description Set TTL for already opened connections when TTL was not set before. Useful for accepted connections when different ones should have different TTL. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>int</type> <funcdef>sk_set_min_ttl</funcdef> (<type>sock *</type> <param>s</param>, <type>int</type> <param>ttl</param>) -- set minimal accepted TTL for given socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket <tagp><type>int</type> <param>ttl</param></tagp> TTL value </descrip> <funcsect>Description Set minimal accepted TTL for given socket. Can be used for TTL security. implementations. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>int</type> <funcdef>sk_set_md5_auth</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket <tagp><type>ip_addr</type> <param>local</param></tagp> IP address of local side <tagp><type>ip_addr</type> <param>remote</param></tagp> IP address of remote side <tagp><type>struct iface *</type> <param>ifa</param></tagp> Interface for link-local IP address <tagp><type>char *</type> <param>passwd</param></tagp> Password used for MD5 authentication <tagp><type>int</type> <param>setkey</param></tagp> Update also system SA/SP database </descrip> <funcsect>Description In TCP MD5 handling code in kernel, there is a set of security associations used for choosing password and other authentication parameters according to the local and remote address. This function is useful for listening socket, for active sockets it may be enough to set s->password field. When called with passwd != NULL, the new pair is added, When called with passwd == NULL, the existing pair is removed. Note that while in Linux, the MD5 SAs are specific to socket, in BSD they are stored in global SA/SP database (but the behavior also must be enabled on per-socket basis). In case of multiple sockets to the same neighbor, the socket-specific state must be configured for each socket while global state just once per src-dst pair. The <param/setkey/ argument controls whether the global state (SA/SP database) is also updated. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>int</type> <funcdef>sk_set_ipv6_checksum</funcdef> (<type>sock *</type> <param>s</param>, <type>int</type> <param>offset</param>) -- specify IPv6 checksum offset for given socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket <tagp><type>int</type> <param>offset</param></tagp> offset </descrip> <funcsect>Description Specify IPv6 checksum field offset for given raw IPv6 socket. After that, the kernel will automatically fill it for outgoing packets and check it for incoming packets. Should not be used on ICMPv6 sockets, where the position is known to the kernel. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>sock *</type> <funcdef>sock_new</funcdef> (<type>pool *</type> <param>p</param>) -- create a socket <funcsect>Arguments <descrip> <tagp><type>pool *</type> <param>p</param></tagp> pool </descrip> <funcsect>Description This function creates a new socket resource. If you want to use it, you need to fill in all the required fields of the structure and call <func/sk_open()/ to do the actual opening of the socket. The real function name is <func/sock_new()/, <func/sk_new()/ is a macro wrapper to avoid collision with OpenSSL. </function> <function><type>int</type> <funcdef>sk_open</funcdef> (<type>sock *</type> <param>s</param>) -- open a socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket </descrip> <funcsect>Description This function takes a socket resource created by <func/sk_new()/ and initialized by the user and binds a corresponding network connection to it. <funcsect>Result 0 for success, -1 for an error. </function> <function><type>int</type> <funcdef>sk_send</funcdef> (<type>sock *</type> <param>s</param>, <type>unsigned</type> <param>len</param>) -- send data to a socket <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket <tagp><type>unsigned</type> <param>len</param></tagp> number of bytes to send </descrip> <funcsect>Description This function sends <param/len/ bytes of data prepared in the transmit buffer of the socket <param/s/ to the network connection. If the packet can be sent immediately, it does so and returns 1, else it queues the packet for later processing, returns 0 and calls the <param/tx_hook/ of the socket when the tranmission takes place. </function> <function><type>int</type> <funcdef>sk_send_to</funcdef> (<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 <funcsect>Arguments <descrip> <tagp><type>sock *</type> <param>s</param></tagp> socket <tagp><type>unsigned</type> <param>len</param></tagp> number of bytes to send <tagp><type>ip_addr</type> <param>addr</param></tagp> IP address to send the packet to <tagp><type>unsigned</type> <param>port</param></tagp> port to send the packet to </descrip> <funcsect>Description This is a <func/sk_send()/ replacement for connection-less packet sockets which allows destination of the packet to be chosen dynamically. Raw IP sockets should use 0 for <param/port/. </function> <function><type>void</type> <funcdef>io_log_event</funcdef> (<type>void *</type> <param>hook</param>, <type>void *</type> <param>data</param>) -- mark approaching event into event log <funcsect>Arguments <descrip> <tagp><type>void *</type> <param>hook</param></tagp> event hook address <tagp><type>void *</type> <param>data</param></tagp> event data address </descrip> <funcsect>Description Store info (hook, data, timestamp) about the following internal event into a circular event log (<param/event_log/). When latency tracking is enabled, the log entry is kept open (in <param/event_open/) so the duration can be filled later. </function> </book>