<!doctype birddoc system>
<!--
BIRD: Programmer's Documentation
Copyright (c) 2000 Martin Mares <mj@ucw.cz>
-->
<book>
<progdoc>
<title>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>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<chapt>BIRD Design
<sect>Introduction
<p>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.
<p>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
<p>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
<p>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
<p>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.
<p>The modules are statically linked to produce a single executable file
(except for the client which stands on its own).
<p>The building process is controlled by a set of Makefiles for GNU Make,
intermixed with several Perl and shell scripts.
<p>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.
<p>The parser of the configuration is generated by the GNU Bison.
<p>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).
<p>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.
<p>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/).
<!--
LocalWords: IPv IP CLI snippets Perl Autoconf SGMLtools DTD SGML dvips
LocalWords: PostScript
-->
<chapt>Core
<sect>Forwarding Information Base
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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).
<p>
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.
<p>
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><p><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
<p><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
<p>
This function initializes a newly allocated FIB and prepares it for use.
</function>
<function><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>fib_free</funcdef>
(<type>struct fib *</type> <param>f</param>) -- delete a FIB
<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
FIB to be deleted
</descrip>
<funcsect>Description
<p>
This function deletes a FIB -- it frees all memory associated
with it and all its entries.
</function>
<function><p><type>void</type>
<funcdef>fib_check</funcdef>
(<type>struct fib *</type> <param>f</param>) -- audit a FIB
<funcsect>Arguments
<p><descrip>
<tagp><type>struct fib *</type> <param>f</param></tagp>
FIB to be checked
</descrip>
<funcsect>Description
<p>
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
<p>
<p>
Routing tables are probably the most important structures BIRD uses. They
hold all the information about known networks, the associated routes and
their attributes.
<p>
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.
<p>
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><p><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
<p><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
<p>
The <func/rte_find()/ function returns a route for destination <param/net/
which is from route source <param/src/.
</function>
<function><p><type>rte *</type>
<funcdef>rte_get_temp</funcdef>
(<type>rta *</type> <param>a</param>) -- get a temporary <struct/rte/
<funcsect>Arguments
<p><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
<p>
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><p><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
<p><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
<p>
<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()/.
<p>
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
<p>
a pointer to the new writable <struct/rte/ with writable <struct/rta/.
</function>
<function><p><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
<p><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
<p>
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.
<p>
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.
<p>
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.
<p>
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><p><type>void</type>
<funcdef>rte_free</funcdef>
(<type>rte *</type> <param>e</param>) -- delete a <struct/rte/
<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
<struct/rte/ to be deleted
</descrip>
<funcsect>Description
<p>
<func/rte_free()/ deletes the given <struct/rte/ from the routing table it's linked to.
</function>
<function><p><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
<p><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
<p>
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()/.
<p>
<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;
<p>
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/.
<p>
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()/.
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>rte_dump</funcdef>
(<type>rte *</type> <param>e</param>) -- dump a route
<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
<struct/rte/ to be dumped
</descrip>
<funcsect>Description
<p>
This functions dumps contents of a <struct/rte/ to debug output.
</function>
<function><p><type>void</type>
<funcdef>rt_dump</funcdef>
(<type>rtable *</type> <param>t</param>) -- dump a routing table
<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>t</param></tagp>
routing table to be dumped
</descrip>
<funcsect>Description
<p>
This function dumps contents of a given routing table to debug output.
</function>
<function><p><type>void</type>
<funcdef>rt_dump_all</funcdef>
(<param>void</param>) -- dump all routing tables
<funcsect>Description
<p>
<p>
This function dumps contents of all routing tables to debug output.
</function>
<function><p><type>void</type>
<funcdef>rt_init</funcdef>
(<param>void</param>) -- initialize routing tables
<funcsect>Description
<p>
<p>
This function is called during BIRD startup. It initializes the
routing table module.
</function>
<function><p><type>int</type>
<funcdef>rt_prune_table</funcdef>
(<type>rtable *</type> <param>tab</param>) -- prune a routing table
<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>tab</param></tagp>
a routing table for pruning
</descrip>
<funcsect>Description
<p>
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.
<p>
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><p><type>int</type>
<funcdef>rt_prune_loop</funcdef>
(<param>void</param>) -- prune routing tables
<funcsect>Description
<p>
<p>
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><p><type>void</type>
<funcdef>rt_lock_table</funcdef>
(<type>rtable *</type> <param>r</param>) -- lock a routing table
<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>r</param></tagp>
routing table to be locked
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>rt_unlock_table</funcdef>
(<type>rtable *</type> <param>r</param>) -- unlock a routing table
<funcsect>Arguments
<p><descrip>
<tagp><type>rtable *</type> <param>r</param></tagp>
routing table to be unlocked
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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><p><type>int</type>
<funcdef>rt_feed_baby</funcdef>
(<type>struct proto *</type> <param>p</param>) -- advertise routes to a new protocol
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
protocol to be fed
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>rt_feed_baby_abort</funcdef>
(<type>struct proto *</type> <param>p</param>) -- abort protocol feeding
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
protocol
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
<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><p><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
<p><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
<p>
<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><p><type>rte *</type>
<funcdef>rte_cow</funcdef>
(<type>rte *</type> <param>r</param>) -- copy a route for writing
<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>r</param></tagp>
a route entry to be copied
</descrip>
<funcsect>Description
<p>
<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.
<p>
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
<p>
a pointer to the new writable <struct/rte/.
</function>
<sect>Route attribute cache
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
Routing tables always contain only cached <struct/rta/'s.
<function><p><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
<p><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
<p>
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/.
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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.
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>ea_sort</funcdef>
(<type>ea_list *</type> <param>e</param>) -- sort an attribute list
<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
list to be sorted
</descrip>
<funcsect>Description
<p>
This function takes a <struct/ea_list/ chain and sorts the attributes
within each of its entries.
<p>
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><p><type>unsigned</type>
<funcdef>ea_scan</funcdef>
(<type>ea_list *</type> <param>e</param>) -- estimate attribute list size
<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
attribute list
</descrip>
<funcsect>Description
<p>
This function calculates an upper bound of the size of
a given <struct/ea_list/ after merging with <func/ea_merge()/.
</function>
<function><p><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
<p><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
<p>
This function takes a possibly multi-segment attribute list
and merges all of its segments to one.
<p>
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><p><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
<p><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
<p>
<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><p><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
<p><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
<p>
This function takes an extended attribute represented by its <struct/eattr/
structure and prints it to the CLI according to the type information.
<p>
If the protocol defining the attribute provides its own
<func/get_attr()/ hook, it's consulted first.
</function>
<function><p><type>void</type>
<funcdef>ea_dump</funcdef>
(<type>ea_list *</type> <param>e</param>) -- dump an extended attribute
<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
attribute to be dumped
</descrip>
<funcsect>Description
<p>
<func/ea_dump()/ dumps contents of the extended attribute given to
the debug output.
</function>
<function><p><type>uint</type>
<funcdef>ea_hash</funcdef>
(<type>ea_list *</type> <param>e</param>) -- calculate an <struct/ea_list/ hash key
<funcsect>Arguments
<p><descrip>
<tagp><type>ea_list *</type> <param>e</param></tagp>
attribute list
</descrip>
<funcsect>Description
<p>
<func/ea_hash()/ takes an extended attribute list and calculated a hopefully
uniformly distributed hash value from its contents.
</function>
<function><p><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
<p><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
<p>
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><p><type>rta *</type>
<funcdef>rta_lookup</funcdef>
(<type>rta *</type> <param>o</param>) -- look up a <struct/rta/ in attribute cache
<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>o</param></tagp>
a un-cached <struct/rta/
</descrip>
<funcsect>Description
<p>
<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.
<p>
The extended attribute lists attached to the <struct/rta/ are automatically
converted to the normalized form.
</function>
<function><p><type>void</type>
<funcdef>rta_dump</funcdef>
(<type>rta *</type> <param>a</param>) -- dump route attributes
<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>a</param></tagp>
attribute structure to dump
</descrip>
<funcsect>Description
<p>
This function takes a <struct/rta/ and dumps its contents to the debug output.
</function>
<function><p><type>void</type>
<funcdef>rta_dump_all</funcdef>
(<param>void</param>) -- dump attribute cache
<funcsect>Description
<p>
<p>
This function dumps the whole contents of route attribute cache
to the debug output.
</function>
<function><p><type>void</type>
<funcdef>rta_init</funcdef>
(<param>void</param>) -- initialize route attribute cache
<funcsect>Description
<p>
<p>
This function is called during initialization of the routing
table module to set up the internals of the attribute cache.
</function>
<function><p><type>rta *</type>
<funcdef>rta_clone</funcdef>
(<type>rta *</type> <param>r</param>) -- clone route attributes
<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>r</param></tagp>
a <struct/rta/ to be cloned
</descrip>
<funcsect>Description
<p>
<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><p><type>void</type>
<funcdef>rta_free</funcdef>
(<type>rta *</type> <param>r</param>) -- free route attributes
<funcsect>Arguments
<p><descrip>
<tagp><type>rta *</type> <param>r</param></tagp>
a <struct/rta/ to be freed
</descrip>
<funcsect>Description
<p>
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>
<!--
BIRD Programmer's Guide: Protocols
(c) 2000 Martin Mares <mj@ucw.cz>
-->
<sect>Routing protocols
<sect1>Introduction
<p>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/ :-).
<p>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.
<p>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.
<p>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).
<p>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
<p>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.
<p>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>
<p>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.
<p>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.
<p>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
<p>The protocol module provides the following functions:
<function><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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.
<p>
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()/).
<p>
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><p><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
<p><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
<p>
Returns pointer to announce hook or NULL
</function>
<function><p><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
<p><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
<p>
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.
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>protos_preconfig</funcdef>
(<type>struct config *</type> <param>c</param>) -- pre-configuration processing
<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
new configuration
</descrip>
<funcsect>Description
<p>
This function calls the <func/preconfig()/ hooks of all routing
protocols available to prepare them for reading of the new
configuration.
</function>
<function><p><type>void</type>
<funcdef>protos_postconfig</funcdef>
(<type>struct config *</type> <param>c</param>) -- post-configuration processing
<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
new configuration
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
Scan differences between <param/old/ and <param/new/ configuration and adjust all
protocol instances to conform to the new configuration.
<p>
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.
<p>
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.
<p>
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
<p>
<p>
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.
<p>
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.
<p>
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).
<p>
The graceful restart recovery is finished when either all graceful restart
locks are unlocked or when graceful restart wait timer fires.
<function><p><type>void</type>
<funcdef>graceful_restart_recovery</funcdef>
(<param>void</param>) -- request initial graceful restart recovery
<funcsect>Graceful restart recovery
<p>
<p>
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><p><type>void</type>
<funcdef>graceful_restart_init</funcdef>
(<param>void</param>) -- initialize graceful restart
<funcsect>Description
<p>
<p>
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><p><type>void</type>
<funcdef>graceful_restart_done</funcdef>
(<type>struct timer *t</type> <param>UNUSED</param>) -- finalize graceful restart
<funcsect>Arguments
<p><descrip>
<tagp><type>struct timer *t</type> <param>UNUSED</param></tagp>
-- undescribed --
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>proto_graceful_restart_lock</funcdef>
(<type>struct proto *</type> <param>p</param>) -- lock graceful restart by protocol
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
protocol instance
</descrip>
<funcsect>Description
<p>
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.
<p>
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><p><type>void</type>
<funcdef>proto_graceful_restart_unlock</funcdef>
(<type>struct proto *</type> <param>p</param>) -- unlock graceful restart by protocol
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
protocol instance
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>protos_dump_all</funcdef>
(<param>void</param>) -- dump status of all protocols
<funcsect>Description
<p>
<p>
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><p><type>void</type>
<funcdef>proto_build</funcdef>
(<type>struct protocol *</type> <param>p</param>) -- make a single protocol available
<funcsect>Arguments
<p><descrip>
<tagp><type>struct protocol *</type> <param>p</param></tagp>
the protocol
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>protos_build</funcdef>
(<param>void</param>) -- build a protocol list
<funcsect>Description
<p>
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>proto_request_feeding</funcdef>
(<type>struct proto *</type> <param>p</param>) -- request feeding routes to the protocol
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
given protocol
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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
<p>
<p>
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><p><type>void</type>
<funcdef>preconfig</funcdef>
(<type>struct protocol *</type> <param>p</param>, <type>struct config *</type> <param>c</param>) -- protocol preconfiguration
<funcsect>Arguments
<p><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
<p>
The <func/preconfig()/ hook is called before parsing of a new configuration.
</function>
<function><p><type>void</type>
<funcdef>postconfig</funcdef>
(<type>struct proto_config *</type> <param>c</param>) -- instance post-configuration
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto_config *</type> <param>c</param></tagp>
instance configuration
</descrip>
<funcsect>Description
<p>
The <func/postconfig()/ hook is called for each configured instance after
parsing of the new configuration is finished.
</function>
<function><p><type>struct proto *</type>
<funcdef>init</funcdef>
(<type>struct proto_config *</type> <param>c</param>) -- initialize an instance
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto_config *</type> <param>c</param></tagp>
instance configuration
</descrip>
<funcsect>Description
<p>
The <func/init()/ hook is called by the core to create a protocol instance
according to supplied protocol configuration.
<funcsect>Result
<p>
a pointer to the instance created
</function>
<function><p><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
<p><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
<p>
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.
<p>
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><p><type>void</type>
<funcdef>dump</funcdef>
(<type>struct proto *</type> <param>p</param>) -- dump protocol state
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
an instance
</descrip>
<funcsect>Description
<p>
This hook dumps the complete state of the instance to the
debug output.
</function>
<function><p><type>void</type>
<funcdef>dump_attrs</funcdef>
(<type>rte *</type> <param>e</param>) -- dump protocol-dependent attributes
<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e</param></tagp>
a route entry
</descrip>
<funcsect>Description
<p>
This hook dumps all attributes in the <struct/rte/ which belong to this
protocol to the debug output.
</function>
<function><p><type>int</type>
<funcdef>start</funcdef>
(<type>struct proto *</type> <param>p</param>) -- request instance startup
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
protocol instance
</descrip>
<funcsect>Description
<p>
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
<p>
new protocol state
</function>
<function><p><type>int</type>
<funcdef>shutdown</funcdef>
(<type>struct proto *</type> <param>p</param>) -- request instance shutdown
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
protocol instance
</descrip>
<funcsect>Description
<p>
The <func/stop()/ hook is called by the core when it wishes to shut
the instance down for some reason.
<funcsect>Returns
<p>
new protocol state
</function>
<function><p><type>void</type>
<funcdef>cleanup</funcdef>
(<type>struct proto *</type> <param>p</param>) -- request instance cleanup
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
protocol instance
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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.
<p>
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.
<p>
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.
<p>
<param/p/->accept_ra_types specifies which kind of route announcements
protocol wants to receive.
</function>
<function><p><type>void</type>
<funcdef>neigh_notify</funcdef>
(<type>neighbor *</type> <param>neigh</param>) -- notify instance about neighbor status change
<funcsect>Arguments
<p><descrip>
<tagp><type>neighbor *</type> <param>neigh</param></tagp>
a neighbor cache entry
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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.
<p>
You must be prepared for any of the attributes being missing
from the list and use default values instead.
</function>
<function><p><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
<p><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
<p>
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.
<p>
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
<p>
1 if the route has to be accepted, -1 if rejected and 0 if it
should be passed to the filters.
</function>
<function><p><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
<p><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
<p>
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
<p>
1 if the ordering implied by <func/rte_better()/ changes enough
that full best route calculation have to be done, 0 otherwise.
</function>
<function><p><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
<p><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
<p>
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
<p>
1 if <param/new/ is better (more preferred) than <param/old/, 0 otherwise.
</function>
<function><p><type>int</type>
<funcdef>rte_same</funcdef>
(<type>rte *</type> <param>e1</param>, <type>rte *</type> <param>e2</param>) -- compare two routes
<funcsect>Arguments
<p><descrip>
<tagp><type>rte *</type> <param>e1</param></tagp>
route
<tagp><type>rte *</type> <param>e2</param></tagp>
route
</descrip>
<funcsect>Description
<p>
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
<p>
1 if <param/e1/ is identical to <param/e2/, 0 otherwise.
</function>
<function><p><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
<p><descrip>
<tagp><type>net *</type> <param>n</param></tagp>
network
<tagp><type>rte *</type> <param>e</param></tagp>
route
</descrip>
<funcsect>Description
<p>
This hook is called whenever a <struct/rte/ belonging to the instance
is accepted for insertion to a routing table.
<p>
Please avoid using this function in new protocols.
</function>
<function><p><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
<p><descrip>
<tagp><type>net *</type> <param>n</param></tagp>
network
<tagp><type>rte *</type> <param>e</param></tagp>
route
</descrip>
<funcsect>Description
<p>
This hook is called whenever a <struct/rte/ belonging to the instance
is removed from a routing table.
<p>
Please avoid using this function in new protocols.
</function>
<sect>Interfaces
<p>
<p>
The interface module keeps track of all network interfaces in the
system and their addresses.
<p>
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/.
<p>
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><p><type>void</type>
<funcdef>ifa_dump</funcdef>
(<type>struct ifa *</type> <param>a</param>) -- dump interface address
<funcsect>Arguments
<p><descrip>
<tagp><type>struct ifa *</type> <param>a</param></tagp>
interface address descriptor
</descrip>
<funcsect>Description
<p>
This function dumps contents of an <struct/ifa/ to the debug output.
</function>
<function><p><type>void</type>
<funcdef>if_dump</funcdef>
(<type>struct iface *</type> <param>i</param>) -- dump interface
<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>i</param></tagp>
interface to dump
</descrip>
<funcsect>Description
<p>
This function dumps all information associated with a given
network interface to the debug output.
</function>
<function><p><type>void</type>
<funcdef>if_dump_all</funcdef>
(<param>void</param>) -- dump all interfaces
<funcsect>Description
<p>
<p>
This function dumps information about all known network
interfaces to the debug output.
</function>
<function><p><type>void</type>
<funcdef>if_delete</funcdef>
(<type>struct iface *</type> <param>old</param>) -- remove interface
<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>old</param></tagp>
interface
</descrip>
<funcsect>Description
<p>
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><p><type>struct iface *</type>
<funcdef>if_update</funcdef>
(<type>struct iface *</type> <param>new</param>) -- update interface status
<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>new</param></tagp>
new interface status
</descrip>
<funcsect>Description
<p>
<func/if_update()/ is called by the low-level platform dependent code
whenever it notices an interface change.
<p>
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.
<p>
<func/if_update()/ will automatically notify all other modules about the change.
</function>
<function><p><type>void</type>
<funcdef>if_feed_baby</funcdef>
(<type>struct proto *</type> <param>p</param>) -- advertise interfaces to a new protocol
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>p</param></tagp>
protocol to feed
</descrip>
<funcsect>Description
<p>
When a new protocol starts, this function sends it a series
of notifications about all existing interfaces.
</function>
<function><p><type>struct iface *</type>
<funcdef>if_find_by_index</funcdef>
(<type>unsigned</type> <param>idx</param>) -- find interface by ifindex
<funcsect>Arguments
<p><descrip>
<tagp><type>unsigned</type> <param>idx</param></tagp>
ifindex
</descrip>
<funcsect>Description
<p>
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><p><type>struct iface *</type>
<funcdef>if_find_by_name</funcdef>
(<type>char *</type> <param>name</param>) -- find interface by name
<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>name</param></tagp>
interface name
</descrip>
<funcsect>Description
<p>
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><p><type>struct ifa *</type>
<funcdef>ifa_update</funcdef>
(<type>struct ifa *</type> <param>a</param>) -- update interface address
<funcsect>Arguments
<p><descrip>
<tagp><type>struct ifa *</type> <param>a</param></tagp>
new interface address
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>ifa_delete</funcdef>
(<type>struct ifa *</type> <param>a</param>) -- remove interface address
<funcsect>Arguments
<p><descrip>
<tagp><type>struct ifa *</type> <param>a</param></tagp>
interface address
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>if_init</funcdef>
(<param>void</param>) -- initialize interface module
<funcsect>Description
<p>
<p>
This function is called during BIRD startup to initialize
all data structures of the interface module.
</function>
<sect>Neighbor cache
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>neigh_dump</funcdef>
(<type>neighbor *</type> <param>n</param>) -- dump specified neighbor entry.
<funcsect>Arguments
<p><descrip>
<tagp><type>neighbor *</type> <param>n</param></tagp>
the entry to dump
</descrip>
<funcsect>Description
<p>
This functions dumps the contents of a given neighbor entry
to debug output.
</function>
<function><p><type>void</type>
<funcdef>neigh_dump_all</funcdef>
(<param>void</param>) -- dump all neighbor entries.
<funcsect>Description
<p>
<p>
This function dumps the contents of the neighbor cache to
debug output.
</function>
<function><p><type>void</type>
<funcdef>neigh_if_up</funcdef>
(<type>struct iface *</type> <param>i</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>i</param></tagp>
interface in question
</descrip>
<funcsect>Description
<p>
Tell the neighbor cache that a new interface became up.
<p>
The neighbor cache wakes up all inactive sticky neighbors with
addresses belonging to prefixes of the interface <param/i/.
</function>
<function><p><type>void</type>
<funcdef>neigh_if_down</funcdef>
(<type>struct iface *</type> <param>i</param>) -- notify neighbor cache about interface down event
<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>i</param></tagp>
the interface in question
</descrip>
<funcsect>Description
<p>
Notify the neighbor cache that an interface has ceased to exist.
<p>
It causes all entries belonging to neighbors connected to this interface
to be flushed.
</function>
<function><p><type>void</type>
<funcdef>neigh_if_link</funcdef>
(<type>struct iface *</type> <param>i</param>) -- notify neighbor cache about interface link change
<funcsect>Arguments
<p><descrip>
<tagp><type>struct iface *</type> <param>i</param></tagp>
the interface in question
</descrip>
<funcsect>Description
<p>
Notify the neighbor cache that an interface changed link state.
All owners of neighbor entries connected to this interface are
notified.
</function>
<function><p><type>void</type>
<funcdef>neigh_ifa_update</funcdef>
(<type>struct ifa *</type> <param>a</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct ifa *</type> <param>a</param></tagp>
interface address in question
</descrip>
<funcsect>Description
<p>
Tell the neighbor cache that an address was added or removed.
<p>
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><p><type>void</type>
<funcdef>neigh_prune</funcdef>
(<param>void</param>) -- prune neighbor cache
<funcsect>Description
<p>
<p>
<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><p><type>void</type>
<funcdef>neigh_init</funcdef>
(<type>pool *</type> <param>if_pool</param>) -- initialize the neighbor cache.
<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>if_pool</param></tagp>
resource pool to be used for neighbor entries.
</descrip>
<funcsect>Description
<p>
This function is called during BIRD startup to initialize
the neighbor cache module.
</function>
<sect>Command line interface
<p>
<p>
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).
<p>
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.
<p>
Reply codes starting with 0 stand for `action successfully completed' messages,
1 means `table entry', 8 `runtime error' and 9 `syntax error'.
<p>
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.
<p>
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.
<p>
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.
<p>
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><p><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
<p><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
<p>
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.
<p>
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.
<p>
If you want to write to the current CLI output, you can use the <func/cli_msg()/
macro instead.
</function>
<function><p><type>void</type>
<funcdef>cli_init</funcdef>
(<param>void</param>) -- initialize the CLI module
<funcsect>Description
<p>
<p>
This function is called during BIRD startup to initialize
the internal data structures of the CLI module.
</function>
<sect>Object locks
<p>
<p>
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.
<p>
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.
<p>
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><p><type>struct object_lock *</type>
<funcdef>olock_new</funcdef>
(<type>pool *</type> <param>p</param>) -- create an object lock
<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
resource pool to create the lock in.
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>olock_acquire</funcdef>
(<type>struct object_lock *</type> <param>l</param>) -- acquire a lock
<funcsect>Arguments
<p><descrip>
<tagp><type>struct object_lock *</type> <param>l</param></tagp>
the lock to acquire
</descrip>
<funcsect>Description
<p>
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.
<p>
When you want to release the resource, just <func/rfree()/ the lock.
</function>
<function><p><type>void</type>
<funcdef>olock_init</funcdef>
(<param>void</param>) -- initialize the object lock mechanism
<funcsect>Description
<p>
<p>
This function is called during BIRD startup. It initializes
all the internal data structures of the lock module.
</function>
<chapt>Configuration
<sect>Configuration manager
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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()/.
<p>
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><p><type>struct config *</type>
<funcdef>config_alloc</funcdef>
(<type>const byte *</type> <param>name</param>) -- allocate a new configuration
<funcsect>Arguments
<p><descrip>
<tagp><type>const byte *</type> <param>name</param></tagp>
name of the config
</descrip>
<funcsect>Description
<p>
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><p><type>int</type>
<funcdef>config_parse</funcdef>
(<type>struct config *</type> <param>c</param>) -- parse a configuration
<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
configuration
</descrip>
<funcsect>Description
<p>
<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
<p>
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><p><type>int</type>
<funcdef>cli_parse</funcdef>
(<type>struct config *</type> <param>c</param>) -- parse a CLI command
<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
temporary config structure
</descrip>
<funcsect>Description
<p>
<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><p><type>void</type>
<funcdef>config_free</funcdef>
(<type>struct config *</type> <param>c</param>) -- free a configuration
<funcsect>Arguments
<p><descrip>
<tagp><type>struct config *</type> <param>c</param></tagp>
configuration to be freed
</descrip>
<funcsect>Description
<p>
This function takes a <struct/config/ structure and frees all resources
associated with it.
</function>
<function><p><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
<p><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
<p>
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.
<p>
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
<p>
<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><p><type>int</type>
<funcdef>config_confirm</funcdef>
(<param>void</param>) -- confirm a commited configuration
<funcsect>Description
<p>
<p>
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
<p>
<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><p><type>int</type>
<funcdef>config_undo</funcdef>
(<param>void</param>) -- undo a configuration
<funcsect>Description
<p>
<p>
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
<p>
<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><p><type>void</type>
<funcdef>order_shutdown</funcdef>
(<param>void</param>) -- order BIRD shutdown
<funcsect>Description
<p>
<p>
This function initiates shutdown of BIRD. It's accomplished by asking
for switching to an empty configuration.
</function>
<function><p><type>void</type>
<funcdef>cf_error</funcdef>
(<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report a configuration error
<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>msg</param></tagp>
printf-like format string
<tagp><type>...</type> <param>...</param></tagp>
variable arguments
</descrip>
<funcsect>Description
<p>
<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><p><type>char *</type>
<funcdef>cfg_strdup</funcdef>
(<type>const char *</type> <param>c</param>) -- copy a string to config memory
<funcsect>Arguments
<p><descrip>
<tagp><type>const char *</type> <param>c</param></tagp>
string to copy
</descrip>
<funcsect>Description
<p>
<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
<p>
<p>
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.
<p>
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/.
<p>
The keyword tables are generated from the grammar templates
using the <tt>gen_keywords.m4</tt> script.
<function><p><type>void</type>
<funcdef>cf_lex_unwind</funcdef>
(<param>void</param>) -- unwind lexer state during error
<funcsect>Lexical analyzer
<p>
<p>
<func/cf_lex_unwind()/ frees the internal state on IFS stack when the lexical
analyzer is terminated by <func/cf_error()/.
</function>
<function><p><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
<p><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
<p>
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><p><type>struct symbol *</type>
<funcdef>cf_get_symbol</funcdef>
(<type>byte *</type> <param>c</param>) -- get a symbol by name
<funcsect>Arguments
<p><descrip>
<tagp><type>byte *</type> <param>c</param></tagp>
symbol name
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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
<p>
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><p><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
<p><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
<p>
<func/cf_lex_init()/ initializes the lexical analyzer and prepares it for
parsing of a new input.
</function>
<function><p><type>void</type>
<funcdef>cf_push_scope</funcdef>
(<type>struct symbol *</type> <param>sym</param>) -- enter new scope
<funcsect>Arguments
<p><descrip>
<tagp><type>struct symbol *</type> <param>sym</param></tagp>
symbol representing scope name
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>cf_pop_scope</funcdef>
(<param>void</param>) -- leave a scope
<funcsect>Description
<p>
<p>
<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><p><type>char *</type>
<funcdef>cf_symbol_class_name</funcdef>
(<type>struct symbol *</type> <param>sym</param>) -- get name of a symbol class
<funcsect>Arguments
<p><descrip>
<tagp><type>struct symbol *</type> <param>sym</param></tagp>
symbol
</descrip>
<funcsect>Description
<p>
This function returns a string representing the class
of the given symbol.
</function>
<sect>Parser
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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
<p>
<p>
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>.
<p>
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.
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
Checks if <param/v1/ is element (<tt>~</tt> operator) of <param/v2/.
</function>
<function><p><type>struct f_val</type>
<funcdef>interpret</funcdef>
(<type>struct f_inst *</type> <param>what</param>)
<funcsect>Arguments
<p><descrip>
<tagp><type>struct f_inst *</type> <param>what</param></tagp>
filter to interpret
</descrip>
<funcsect>Description
<p>
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
<p>
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.
<p>
<struct/f_val/ structures are copied around, so there are no problems with
memory managment.
</function>
<function><p><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
<p><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
<p>
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).
<p>
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.
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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.
<p>
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><p><type>struct f_tree *</type>
<funcdef>build_tree</funcdef>
(<type>struct f_tree *</type> <param>from</param>)
<funcsect>Arguments
<p><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
<p>
Transforms degenerated tree into balanced tree.
</function>
<function><p><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
<p><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
<p>
Compares two trees and returns 1 if they are same
</function>
<sect>Trie for prefix sets
<p>
<p>
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/.
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
There are four cases when we walk through a trie:
<p>
- 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/)
<p>
The walking code in <func/trie_match_prefix()/ is structured according to
these cases.
<function><p><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
<p><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><p><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
<p><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
<p>
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).
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
Compares two tries and returns 1 if they are same
</function>
<function><p><type>void</type>
<funcdef>trie_format</funcdef>
(<type>struct f_trie *</type> <param>t</param>, <type>buffer *</type> <param>buf</param>)
<funcsect>Arguments
<p><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
<p>
Prints the trie to the supplied buffer.
</function>
<chapt>Protocols
<sect>The Babel protocol
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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><p><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
<p><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
<p>
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><p><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
<p><descrip>
<tagp><type>struct babel_entry *</type> <param>e</param></tagp>
Babel entry to select the best route for
</descrip>
<funcsect>Description
<p>
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.
<p>
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).
<p>
If no feasible route is available, and no previous route is selected, the
route is removed from the nest entirely.
</function>
<function><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>babel_iface_timer</funcdef>
(<type>timer *</type> <param>t</param>) -- Babel interface timer handler
<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
Timer
</descrip>
<funcsect>Description
<p>
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.
<p>
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.
<p>
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><p><type>void</type>
<funcdef>babel_timer</funcdef>
(<type>timer *</type> <param>t</param>) -- global timer hook
<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
Timer
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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.
<p>
The TLVs in the queue are freed after they are written to the buffer.
</function>
<function><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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.
<p>
After the parsing step, the TLV handlers are called for each parsed TLV in
order.
</function>
<sect>Bidirectional Forwarding Detection
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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()/.
<p>
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.
<p>
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.
<p>
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.
<p>
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()/.
<p>
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).
<p>
TODO: document functions and access restrictions for fields in BFD structures.
<p>
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
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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><p><type>int</type>
<funcdef>bgp_open</funcdef>
(<type>struct bgp_proto *</type> <param>p</param>) -- open a BGP instance
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
BGP instance
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>bgp_close_conn</funcdef>
(<type>struct bgp_conn *</type> <param>conn</param>) -- close a BGP connection
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
connection to close
</descrip>
<funcsect>Description
<p>
This function takes a connection described by the <struct/bgp_conn/ structure,
closes its socket and frees all resources associated with it.
</function>
<function><p><type>void</type>
<funcdef>bgp_update_startup_delay</funcdef>
(<type>struct bgp_proto *</type> <param>p</param>) -- update a startup delay
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
BGP instance
</descrip>
<funcsect>Description
<p>
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.
<p>
It should be called when BGP protocol error happened.
</function>
<function><p><type>void</type>
<funcdef>bgp_handle_graceful_restart</funcdef>
(<type>struct bgp_proto *</type> <param>p</param>) -- handle detected BGP graceful restart
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
BGP instance
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>bgp_graceful_restart_done</funcdef>
(<type>struct bgp_proto *</type> <param>p</param>) -- finish active BGP graceful restart
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
BGP instance
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>bgp_graceful_restart_timeout</funcdef>
(<type>timer *</type> <param>t</param>) -- timeout of graceful restart 'restart timer'
<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
timer
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>bgp_refresh_begin</funcdef>
(<type>struct bgp_proto *</type> <param>p</param>) -- start incoming enhanced route refresh sequence
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
BGP instance
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>bgp_refresh_end</funcdef>
(<type>struct bgp_proto *</type> <param>p</param>) -- finish incoming enhanced route refresh sequence
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
BGP instance
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>bgp_connect</funcdef>
(<type>struct bgp_proto *</type> <param>p</param>) -- initiate an outgoing connection
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
BGP instance
</descrip>
<funcsect>Description
<p>
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><p><type>struct bgp_proto *</type>
<funcdef>bgp_find_proto</funcdef>
(<type>sock *</type> <param>sk</param>) -- find existing proto for incoming connection
<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>sk</param></tagp>
TCP socket
</descrip>
</function>
<function><p><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
<p><descrip>
<tagp><type>sock *</type> <param>sk</param></tagp>
TCP socket
<tagp><type>uint dummy</type> <param>UNUSED</param></tagp>
-- undescribed --
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
<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><p><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
<p><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
<p>
<func/bgp_store_error()/ decides whether given error is interesting enough
and store that error to last_error variables of <param/p/
</function>
<function><p><type>int</type>
<funcdef>bgp_fire_tx</funcdef>
(<type>struct bgp_conn *</type> <param>conn</param>) -- transmit packets
<funcsect>Arguments
<p><descrip>
<tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
connection
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
Schedule a packet of type <param/type/ to be sent as soon as possible.
</function>
<function><p><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
<p><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
<p>
<func/bgp_error_dsc()/ returns error description for BGP errors
which might be static string or given temporary buffer.
</function>
<function><p><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
<p><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
<p>
<func/bgp_rx_packet()/ takes a newly received packet and calls the corresponding
packet handler according to the packet type.
</function>
<function><p><type>int</type>
<funcdef>bgp_rx</funcdef>
(<type>sock *</type> <param>sk</param>, <type>uint</type> <param>size</param>) -- handle received data
<funcsect>Arguments
<p><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
<p>
<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><p><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
<p><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
<p>
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
<p>
Length of the attribute block generated or -1 if not enough space.
</function>
<function><p><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
<p><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
<p>
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
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
Supported standards:
- RFC 6396 - MRT format standard
- RFC 8050 - ADD_PATH extension
<sect>Open Shortest Path First (OSPF)
<p>
<p>
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.).
<p>
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.
<p>
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.
<p>
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.
<p>
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()/).
<p>
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.
<p>
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.
<p>
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/.
<p>
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.
<p>
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><p><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
<p><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><p><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
<p><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
<p>
Its quite simple. It does not accept our own routes and leaves the decision on
import to the filters.
</function>
<function><p><type>int</type>
<funcdef>ospf_shutdown</funcdef>
(<type>struct proto *</type> <param>P</param>) -- Finish of OSPF instance
<funcsect>Arguments
<p><descrip>
<tagp><type>struct proto *</type> <param>P</param></tagp>
OSPF protocol instance
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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()/.
<p>
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><p><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
<p><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
<p>
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).
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>ospf_update_lsadb</funcdef>
(<type>struct ospf_proto *</type> <param>p</param>) -- update LSA database
<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
OSPF protocol instance
</descrip>
<funcsect>Description
<p>
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/.
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>ospf_dr_election</funcdef>
(<type>struct ospf_iface *</type> <param>ifa</param>) -- (Backup) Designed Router election
<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
actual interface
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>int</type>
<funcdef>ospf_rx_hook</funcdef>
(<type>sock *</type> <param>sk</param>, <type>uint</type> <param>len</param>)
<funcsect>Arguments
<p><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
<p>
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><p><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
<p><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
<p>
Checks internal structure of given LSA body (minimal length,
consistency). Returns true if valid.
</function>
<function><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>ospf_rt_spf</funcdef>
(<type>struct ospf_proto *</type> <param>p</param>) -- calculate internal routes
<funcsect>Arguments
<p><descrip>
<tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
OSPF protocol instance
</descrip>
<funcsect>Description
<p>
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
<p>
<p>
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.
<p>
To avoid pipe loops, Pipe keeps a `being updated' flag in each routing
table.
<p>
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)
<p>
<p>
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.
<p>
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.
<p>
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).
<p>
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()/.
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
Supported standards:
- RFC 1058 - RIPv1
- RFC 2453 - RIPv2
- RFC 2080 - RIPng
- RFC 4822 - RIP cryptographic authentication
<function><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>void</type>
<funcdef>rip_timer</funcdef>
(<type>timer *</type> <param>t</param>) -- RIP main timer hook
<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
timer
</descrip>
<funcsect>Description
<p>
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()/.
<p>
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.
<p>
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><p><type>void</type>
<funcdef>rip_iface_timer</funcdef>
(<type>timer *</type> <param>t</param>) -- RIP interface timer hook
<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
timer
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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
<p>
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
Supported standards:
- RFC 4861 - main RA standard
- RFC 4191 - Default Router Preferences and More-Specific Routes
- RFC 6106 - DNS extensions (RDDNS, DNSSL)
<sect>Static
<p>
<p>
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.
<p>
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.
<p>
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
<p>
<p>
The Direct protocol works by converting all <func/ifa_notify()/ events it receives
to <func/rte_update()/ calls for the corresponding network.
<!--
BIRD Programmer's Guide: Sysdeps
(c) 2000 Martin Mares <mj@ucw.cz>
-->
<chapt>System dependent parts
<sect>Introduction
<p>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
<p>
<p>
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><p><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
<p><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
<p>
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.
<p>
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><p><type>void</type>
<funcdef>log_msg</funcdef>
(<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- log a message
<funcsect>Arguments
<p><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
<p>
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><p><type>void</type>
<funcdef>bug</funcdef>
(<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report an internal error
<funcsect>Arguments
<p><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
<p>
This function logs an internal error and aborts execution
of the program.
</function>
<function><p><type>void</type>
<funcdef>die</funcdef>
(<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report a fatal error
<funcsect>Arguments
<p><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
<p>
This function logs a fatal error and aborts execution
of the program.
</function>
<function><p><type>void</type>
<funcdef>debug</funcdef>
(<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- write to debug output
<funcsect>Arguments
<p><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
<p>
This function formats the message <param/msg/ and prints it out
to the debugging output. No newline character is appended.
</function>
<sect>Kernel synchronization
<p>
<p>
This system dependent module implements the Kernel and Device protocol,
that is synchronization of interface lists and routing tables with the
OS kernel.
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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
<p>
<p>
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><p><type>char *</type>
<funcdef>ip_scope_text</funcdef>
(<type>uint</type> <param>scope</param>) -- get textual representation of address scope
<funcsect>Arguments
<p><descrip>
<tagp><type>uint</type> <param>scope</param></tagp>
scope (<const/SCOPE_xxx/)
</descrip>
<funcsect>Description
<p>
Returns a pointer to a textual name of the scope given.
</function>
<function><p><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
<p><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
<p>
<func/ipa_equal()/ returns 1 if <param/x/ and <param/y/ represent the same IP address, else 0.
</function>
<function><p><type>int</type>
<funcdef>ipa_nonzero</funcdef>
(<type>ip_addr</type> <param>x</param>) -- test if an IP address is defined
<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
IP address
</descrip>
<funcsect>Description
<p>
ipa_nonzero returns 1 if <param/x/ is a defined IP address (not all bits are zero),
else 0.
<p>
The undefined all-zero address is reachable as a <tt>IPA_NONE</tt> macro.
</function>
<function><p><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
<p><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
<p>
This function returns a bitwise and of <param/x/ and <param/y/. It's primarily
used for network masking.
</function>
<function><p><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
<p><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
<p>
This function returns a bitwise or of <param/x/ and <param/y/.
</function>
<function><p><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
<p><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
<p>
This function returns a bitwise xor of <param/x/ and <param/y/.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_not</funcdef>
(<type>ip_addr</type> <param>x</param>) -- compute bitwise negation of two IP addresses
<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
IP address
</descrip>
<funcsect>Description
<p>
This function returns a bitwise negation of <param/x/.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_mkmask</funcdef>
(<type>int</type> <param>x</param>) -- create a netmask
<funcsect>Arguments
<p><descrip>
<tagp><type>int</type> <param>x</param></tagp>
prefix length
</descrip>
<funcsect>Description
<p>
This function returns an <struct/ip_addr/ corresponding of a netmask
of an address prefix of size <param/x/.
</function>
<function><p><type>int</type>
<funcdef>ipa_masklen</funcdef>
(<type>ip_addr</type> <param>x</param>) -- calculate netmask length
<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
IP address
</descrip>
<funcsect>Description
<p>
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><p><type>int</type>
<funcdef>ipa_hash</funcdef>
(<type>ip_addr</type> <param>x</param>) -- hash IP addresses
<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
IP address
</descrip>
<funcsect>Description
<p>
<func/ipa_hash()/ returns a 16-bit hash value of the IP address <param/x/.
</function>
<function><p><type>void</type>
<funcdef>ipa_hton</funcdef>
(<type>ip_addr</type> <param>x</param>) -- convert IP address to network order
<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
IP address
</descrip>
<funcsect>Description
<p>
Converts the IP address <param/x/ to the network byte order.
<p>
Beware, this is a macro and it alters the argument!
</function>
<function><p><type>void</type>
<funcdef>ipa_ntoh</funcdef>
(<type>ip_addr</type> <param>x</param>) -- convert IP address to host order
<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
IP address
</descrip>
<funcsect>Description
<p>
Converts the IP address <param/x/ from the network byte order.
<p>
Beware, this is a macro and it alters the argument!
</function>
<function><p><type>int</type>
<funcdef>ipa_classify</funcdef>
(<type>ip_addr</type> <param>x</param>) -- classify an IP address
<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
IP address
</descrip>
<funcsect>Description
<p>
<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><p><type>ip4_addr</type>
<funcdef>ip4_class_mask</funcdef>
(<type>ip4_addr</type> <param>x</param>) -- guess netmask according to address class
<funcsect>Arguments
<p><descrip>
<tagp><type>ip4_addr</type> <param>x</param></tagp>
IPv4 address
</descrip>
<funcsect>Description
<p>
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><p><type>u32</type>
<funcdef>ipa_from_u32</funcdef>
(<type>ip_addr</type> <param>x</param>) -- convert IPv4 address to an integer
<funcsect>Arguments
<p><descrip>
<tagp><type>ip_addr</type> <param>x</param></tagp>
IP address
</descrip>
<funcsect>Description
<p>
This function takes an IPv4 address and returns its numeric
representation.
</function>
<function><p><type>ip_addr</type>
<funcdef>ipa_to_u32</funcdef>
(<type>u32</type> <param>x</param>) -- convert integer to IPv4 address
<funcsect>Arguments
<p><descrip>
<tagp><type>u32</type> <param>x</param></tagp>
a 32-bit integer
</descrip>
<funcsect>Description
<p>
<func/ipa_to_u32()/ takes a numeric representation of an IPv4 address
and converts it to the corresponding <struct/ip_addr/.
</function>
<function><p><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
<p><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
<p>
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><p><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
<p><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
<p>
<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><p><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
<p><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
<p>
This function takes an IP address and creates its textual
representation for presenting to the user.
</function>
<function><p><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
<p><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
<p>
This function takes an IP address and creates its hexadecimal
textual representation. Primary use: debugging dumps.
</function>
<function><p><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
<p><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
<p>
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
<p>
<p>
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.
<p>
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><p><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
<p><descrip>
<tagp><type>list *</type> <param>l</param></tagp>
linked list
<tagp><type>node *</type> <param>n</param></tagp>
list node
</descrip>
<funcsect>Description
<p>
<func/add_tail()/ takes a node <param/n/ and appends it at the end of the list <param/l/.
</function>
<function><p><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
<p><descrip>
<tagp><type>list *</type> <param>l</param></tagp>
linked list
<tagp><type>node *</type> <param>n</param></tagp>
list node
</descrip>
<funcsect>Description
<p>
<func/add_head()/ takes a node <param/n/ and prepends it at the start of the list <param/l/.
</function>
<function><p><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
<p><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
<p>
Inserts a node <param/n/ to a linked list after an already inserted
node <param/after/.
</function>
<function><p><type>LIST_INLINE void</type>
<funcdef>rem_node</funcdef>
(<type>node *</type> <param>n</param>) -- remove a node from a list
<funcsect>Arguments
<p><descrip>
<tagp><type>node *</type> <param>n</param></tagp>
node to be removed
</descrip>
<funcsect>Description
<p>
Removes a node <param/n/ from the list it's linked in. Afterwards, node <param/n/ is cleared.
</function>
<function><p><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
<p><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
<p>
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><p><type>LIST_INLINE void</type>
<funcdef>init_list</funcdef>
(<type>list *</type> <param>l</param>) -- create an empty list
<funcsect>Arguments
<p><descrip>
<tagp><type>list *</type> <param>l</param></tagp>
list
</descrip>
<funcsect>Description
<p>
<func/init_list()/ takes a <struct/list/ structure and initializes its
fields, so that it represents an empty list.
</function>
<function><p><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
<p><descrip>
<tagp><type>list *</type> <param>to</param></tagp>
destination list
<tagp><type>list *</type> <param>l</param></tagp>
source list
</descrip>
<funcsect>Description
<p>
This function appends all elements of the list <param/l/ to
the list <param/to/ in constant time.
</function>
<sect>Miscellaneous functions.
<p>
<function><p><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
<p><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
<p>
This function verifies whether a given fragmented packet
has correct one's complement checksum as used by the IP
protocol.
<p>
It uses all the clever tricks described in RFC 1071 to speed
up checksum calculation as much as possible.
<funcsect>Result
<p>
1 if the checksum is correct, 0 else.
</function>
<function><p><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
<p><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
<p>
This function calculates a one's complement checksum of a given fragmented
packet.
<p>
It uses all the clever tricks described in RFC 1071 to speed
up checksum calculation as much as possible.
</function>
<function><p><type>u32</type>
<funcdef>u32_mkmask</funcdef>
(<type>uint</type> <param>n</param>) -- create a bit mask
<funcsect>Arguments
<p><descrip>
<tagp><type>uint</type> <param>n</param></tagp>
number of bits
</descrip>
<funcsect>Description
<p>
<func/u32_mkmask()/ returns an unsigned 32-bit integer which binary
representation consists of <param/n/ ones followed by zeroes.
</function>
<function><p><type>int</type>
<funcdef>u32_masklen</funcdef>
(<type>u32</type> <param>x</param>) -- calculate length of a bit mask
<funcsect>Arguments
<p><descrip>
<tagp><type>u32</type> <param>x</param></tagp>
bit mask
</descrip>
<funcsect>Description
<p>
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><p><type>u32</type>
<funcdef>u32_log2</funcdef>
(<type>u32</type> <param>v</param>) -- compute a binary logarithm.
<funcsect>Arguments
<p><descrip>
<tagp><type>u32</type> <param>v</param></tagp>
number
</descrip>
<funcsect>Description
<p>
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><p><type>int</type>
<funcdef>patmatch</funcdef>
(<type>byte *</type> <param>p</param>, <type>byte *</type> <param>s</param>) -- match shell-like patterns
<funcsect>Arguments
<p><descrip>
<tagp><type>byte *</type> <param>p</param></tagp>
pattern
<tagp><type>byte *</type> <param>s</param></tagp>
string
</descrip>
<funcsect>Description
<p>
<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.
<p>
The matching process is not optimized with respect to time, so please
avoid using this function for complex patterns.
</function>
<function><p><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
<p><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
<p>
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
<p>
<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
<p>
number of characters of the output string or -1 if
the buffer space was insufficient.
</function>
<function><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
This function is equivalent to <func/bsnprintf()/ with variable arguments instead of a <struct/va_list/.
</function>
<function><p><type>void *</type>
<funcdef>xmalloc</funcdef>
(<type>uint</type> <param>size</param>) -- malloc with checking
<funcsect>Arguments
<p><descrip>
<tagp><type>uint</type> <param>size</param></tagp>
block size
</descrip>
<funcsect>Description
<p>
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.
<p>
Wherever possible, please use the memory resources instead.
</function>
<function><p><type>void *</type>
<funcdef>xrealloc</funcdef>
(<type>void *</type> <param>ptr</param>, <type>uint</type> <param>size</param>) -- realloc with checking
<funcsect>Arguments
<p><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
<p>
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.
<p>
Wherever possible, please use the memory resources instead.
</function>
<sect>Message authentication codes
<p>
<p>
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.
<p>
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.
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><type>byte *</type>
<funcdef>mac_final</funcdef>
(<type>struct mac_context *</type> <param>ctx</param>) -- finalize MAC algorithm
<funcsect>Arguments
<p><descrip>
<tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
MAC context
</descrip>
<funcsect>Description
<p>
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.
<p>
Note that the returned pointer points into data in the <param/ctx/ context. If it
ceases to exist, the pointer becomes invalid.
</function>
<function><p><type>void</type>
<funcdef>mac_cleanup</funcdef>
(<type>struct mac_context *</type> <param>ctx</param>) -- cleanup MAC context
<funcsect>Arguments
<p><descrip>
<tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
MAC context
</descrip>
<funcsect>Description
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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>
<!--
BIRD Programmer's Guide: Resources
(c) 2000 Martin Mares <mj@ucw.cz>
-->
<chapt>Resources
<sect>Introduction
<p>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.
<p>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.
<p>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.
<p>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
<p>
<p>
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.
<p>
Example: Almost all modules of BIRD have their private pool which
is freed upon shutdown of the module.
<function><p><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
<p><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
<p>
<func/rp_new()/ creates a new resource pool inside the specified
parent pool.
</function>
<function><p><type>void</type>
<funcdef>rmove</funcdef>
(<type>void *</type> <param>res</param>, <type>pool *</type> <param>p</param>) -- move a resource
<funcsect>Arguments
<p><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
<p>
<func/rmove()/ moves a resource from one pool to another.
</function>
<function><p><type>void</type>
<funcdef>rfree</funcdef>
(<type>void *</type> <param>res</param>) -- free a resource
<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>res</param></tagp>
resource
</descrip>
<funcsect>Description
<p>
<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.
<p>
It works by calling a class-specific freeing function.
</function>
<function><p><type>void</type>
<funcdef>rdump</funcdef>
(<type>void *</type> <param>res</param>) -- dump a resource
<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>res</param></tagp>
resource
</descrip>
<funcsect>Description
<p>
This function prints out all available information about the given
resource to the debugging output.
<p>
It works by calling a class-specific dump function.
</function>
<function><p><type>void *</type>
<funcdef>ralloc</funcdef>
(<type>pool *</type> <param>p</param>, <type>struct resclass *</type> <param>c</param>) -- create a resource
<funcsect>Arguments
<p><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
<p>
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><p><type>void</type>
<funcdef>rlookup</funcdef>
(<type>unsigned long</type> <param>a</param>) -- look up a memory location
<funcsect>Arguments
<p><descrip>
<tagp><type>unsigned long</type> <param>a</param></tagp>
memory address
</descrip>
<funcsect>Description
<p>
This function examines all existing resources to see whether
the address <param/a/ is inside any resource. It's used for debugging
purposes only.
<p>
It works by calling a class-specific lookup function for each
resource.
</function>
<function><p><type>void</type>
<funcdef>resource_init</funcdef>
(<param>void</param>) -- initialize the resource manager
<funcsect>Description
<p>
<p>
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
<p>
<p>
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.
<p>
Example: All "unique" data structures such as hash tables are allocated
as memory blocks.
<function><p><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
<p><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
<p>
<func/mb_alloc()/ allocates memory of a given size and creates
a memory block resource representing this memory chunk
in the pool <param/p/.
<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><p><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
<p><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
<p>
<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/.
<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><p><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
<p><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
<p>
<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.
<p>
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><p><type>void</type>
<funcdef>mb_free</funcdef>
(<type>void *</type> <param>m</param>) -- free a memory block
<funcsect>Arguments
<p><descrip>
<tagp><type>void *</type> <param>m</param></tagp>
memory block
</descrip>
<funcsect>Description
<p>
<func/mb_free()/ frees all memory associated with the block <param/m/.
</function>
<sect>Linear memory pools
<p>
<p>
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.
<p>
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><p><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
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
pool
<tagp><type>uint</type> <param>blk</param></tagp>
block size
</descrip>
<funcsect>Description
<p>
<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><p><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
<p><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
<p>
<func/lp_alloc()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/
and it returns a pointer to the allocated memory.
<p>
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><p><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
<p><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
<p>
<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><p><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
<p><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
<p>
This function is identical to <func/lp_alloc()/ except that it
clears the allocated memory block.
</function>
<function><p><type>void</type>
<funcdef>lp_flush</funcdef>
(<type>linpool *</type> <param>m</param>) -- flush a linear memory pool
<funcsect>Arguments
<p><descrip>
<tagp><type>linpool *</type> <param>m</param></tagp>
linear memory pool
</descrip>
<funcsect>Description
<p>
This function frees the whole contents of the given <struct/linpool/ <param/m/,
but leaves the pool itself.
</function>
<sect>Slabs
<p>
<p>
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.
<p>
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.
<p>
Example: Nodes of a FIB are allocated from a per-FIB Slab.
<function><p><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
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
resource pool
<tagp><type>uint</type> <param>size</param></tagp>
block size
</descrip>
<funcsect>Description
<p>
This function creates a new Slab resource from which
objects of size <param/size/ can be allocated.
</function>
<function><p><type>void *</type>
<funcdef>sl_alloc</funcdef>
(<type>slab *</type> <param>s</param>) -- allocate an object from Slab
<funcsect>Arguments
<p><descrip>
<tagp><type>slab *</type> <param>s</param></tagp>
slab
</descrip>
<funcsect>Description
<p>
<func/sl_alloc()/ allocates space for a single object from the
Slab and returns a pointer to the object.
</function>
<function><p><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
<p><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
<p>
This function frees memory associated with the object <param/oo/
and returns it back to the Slab <param/s/.
</function>
<sect>Events
<p>
<p>
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.
<p>
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><p><type>event *</type>
<funcdef>ev_new</funcdef>
(<type>pool *</type> <param>p</param>) -- create a new event
<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
resource pool
</descrip>
<funcsect>Description
<p>
This function creates a new event resource. To use it,
you need to fill the structure fields and call <func/ev_schedule()/.
</function>
<function><p><type>void</type>
<funcdef>ev_run</funcdef>
(<type>event *</type> <param>e</param>) -- run an event
<funcsect>Arguments
<p><descrip>
<tagp><type>event *</type> <param>e</param></tagp>
an event
</descrip>
<funcsect>Description
<p>
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.
<p>
From the hook function, you can call <func/ev_enqueue()/ or <func/ev_schedule()/
to re-add the event.
</function>
<function><p><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
<p><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
<p>
<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><p><type>void</type>
<funcdef>ev_schedule</funcdef>
(<type>event *</type> <param>e</param>) -- schedule an event
<funcsect>Arguments
<p><descrip>
<tagp><type>event *</type> <param>e</param></tagp>
an event
</descrip>
<funcsect>Description
<p>
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><p><type>int</type>
<funcdef>ev_run_list</funcdef>
(<type>event_list *</type> <param>l</param>) -- run an event list
<funcsect>Arguments
<p><descrip>
<tagp><type>event_list *</type> <param>l</param></tagp>
an event list
</descrip>
<funcsect>Description
<p>
This function calls <func/ev_run()/ for all events enqueued in the list <param/l/.
</function>
<sect>Timers
<p>
<p>
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.
<p>
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.
<p>
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><p><type>timer *</type>
<funcdef>tm_new</funcdef>
(<type>pool *</type> <param>p</param>) -- create a timer
<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
pool
</descrip>
<funcsect>Description
<p>
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><p><type>void</type>
<funcdef>tm_start</funcdef>
(<type>timer *</type> <param>t</param>, <type>unsigned</type> <param>after</param>) -- start a timer
<funcsect>Arguments
<p><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
<p>
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.
<p>
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/.
<p>
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><p><type>void</type>
<funcdef>tm_stop</funcdef>
(<type>timer *</type> <param>t</param>) -- stop a timer
<funcsect>Arguments
<p><descrip>
<tagp><type>timer *</type> <param>t</param></tagp>
timer
</descrip>
<funcsect>Description
<p>
This function stops a timer. If the timer is already stopped,
nothing happens.
</function>
<function><p><type>bird_clock_t</type>
<funcdef>tm_parse_datetime</funcdef>
(<type>char *</type> <param>x</param>) -- parse a date and time
<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>x</param></tagp>
datetime string
</descrip>
<funcsect>Description
<p>
<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><p><type>bird_clock_t</type>
<funcdef>tm_parse_date</funcdef>
(<type>char *</type> <param>x</param>) -- parse a date
<funcsect>Arguments
<p><descrip>
<tagp><type>char *</type> <param>x</param></tagp>
date string
</descrip>
<funcsect>Description
<p>
<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><p><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
<p><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
<p>
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
<p>
<p>
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/).
<p>
Freeing of sockets from inside socket hooks is perfectly safe.
<function><p><type>int</type>
<funcdef>sk_setup_multicast</funcdef>
(<type>sock *</type> <param>s</param>) -- enable multicast for given socket
<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
socket
</descrip>
<funcsect>Description
<p>
Prepare transmission of multicast packets for given datagram socket.
The socket must have defined <param/iface/.
<funcsect>Result
<p>
0 for success, -1 for an error.
</function>
<function><p><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
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
socket
<tagp><type>ip_addr</type> <param>maddr</param></tagp>
multicast address
</descrip>
<funcsect>Description
<p>
Join multicast group for given datagram socket and associated interface.
The socket must have defined <param/iface/.
<funcsect>Result
<p>
0 for success, -1 for an error.
</function>
<function><p><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
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
socket
<tagp><type>ip_addr</type> <param>maddr</param></tagp>
multicast address
</descrip>
<funcsect>Description
<p>
Leave multicast group for given datagram socket and associated interface.
The socket must have defined <param/iface/.
<funcsect>Result
<p>
0 for success, -1 for an error.
</function>
<function><p><type>int</type>
<funcdef>sk_setup_broadcast</funcdef>
(<type>sock *</type> <param>s</param>) -- enable broadcast for given socket
<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
socket
</descrip>
<funcsect>Description
<p>
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
<p>
0 for success, -1 for an error.
</function>
<function><p><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
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
socket
<tagp><type>int</type> <param>ttl</param></tagp>
TTL value
</descrip>
<funcsect>Description
<p>
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
<p>
0 for success, -1 for an error.
</function>
<function><p><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
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
socket
<tagp><type>int</type> <param>ttl</param></tagp>
TTL value
</descrip>
<funcsect>Description
<p>
Set minimal accepted TTL for given socket. Can be used for TTL security.
implementations.
<funcsect>Result
<p>
0 for success, -1 for an error.
</function>
<function><p><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
<p><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
<p>
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.
<p>
When called with passwd != NULL, the new pair is added,
When called with passwd == NULL, the existing pair is removed.
<p>
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
<p>
0 for success, -1 for an error.
</function>
<function><p><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
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
socket
<tagp><type>int</type> <param>offset</param></tagp>
offset
</descrip>
<funcsect>Description
<p>
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
<p>
0 for success, -1 for an error.
</function>
<function><p><type>sock *</type>
<funcdef>sock_new</funcdef>
(<type>pool *</type> <param>p</param>) -- create a socket
<funcsect>Arguments
<p><descrip>
<tagp><type>pool *</type> <param>p</param></tagp>
pool
</descrip>
<funcsect>Description
<p>
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.
<p>
The real function name is <func/sock_new()/, <func/sk_new()/ is a macro wrapper
to avoid collision with OpenSSL.
</function>
<function><p><type>int</type>
<funcdef>sk_open</funcdef>
(<type>sock *</type> <param>s</param>) -- open a socket
<funcsect>Arguments
<p><descrip>
<tagp><type>sock *</type> <param>s</param></tagp>
socket
</descrip>
<funcsect>Description
<p>
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
<p>
0 for success, -1 for an error.
</function>
<function><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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><p><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
<p><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
<p>
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>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog.sgml CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird2 / doc