Commit 58740ed4 authored by Martin Mareš's avatar Martin Mareš

Documentation.

parent 658d272b
H Core H Core
S rt-fib.c
S rt-table.c
S neighbor.c S neighbor.c
#S rt-attr.c
#S cli.c #S cli.c
#S iface.c #S iface.c
S locks.c S locks.c
#S proto.c #S proto.c
#S rt-attr.c
#S rt-dev.c
S rt-fib.c
#S rt-table.c
/* /*
* BIRD -- Routing Table * BIRD -- Routing Tables
* *
* (c) 1998--2000 Martin Mares <mj@ucw.cz> * (c) 1998--2000 Martin Mares <mj@ucw.cz>
* *
* Can be freely distributed and used under the terms of the GNU GPL. * Can be freely distributed and used under the terms of the GNU GPL.
*/ */
/**
* DOC: Routing tables
*
* Routing tables are probably the most important structures BIRD uses. They
* hold all the information about known networks, the associated routes and
* their attributes.
*
* There exist 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 &net)
* there is a one-way linked list of network entries (&rte), the first entry
* on the list being the best possible one (i.e., the one we currently use
* for routing), the order of the other ones is undetermined.
*
* The &rte contains information specific to the route (preference, protocol
* metrics, time of last modification etc.) and a pointer to a &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.
*/
#undef LOCAL_DEBUG #undef LOCAL_DEBUG
#include "nest/bird.h" #include "nest/bird.h"
...@@ -37,6 +59,14 @@ rte_init(struct fib_node *N) ...@@ -37,6 +59,14 @@ rte_init(struct fib_node *N)
n->routes = NULL; n->routes = NULL;
} }
/**
* rte_find - find a route
* @net: network node
* @p: protocol
*
* The rte_find() function returns a route for destination @net
* which belongs has been defined by protocol @p.
*/
rte * rte *
rte_find(net *net, struct proto *p) rte_find(net *net, struct proto *p)
{ {
...@@ -47,6 +77,14 @@ rte_find(net *net, struct proto *p) ...@@ -47,6 +77,14 @@ rte_find(net *net, struct proto *p)
return e; return e;
} }
/**
* rte_get_temp - get a temporary &rte
* @a: attributes to assign to the new route (a &rta)
*
* Create a temporary &rte and bind it with the attributes @a.
* Also set route preference to the default preference set for
* the protocol.
*/
rte * rte *
rte_get_temp(rta *a) rte_get_temp(rta *a)
{ {
...@@ -243,6 +281,12 @@ rte_validate(rte *e) ...@@ -243,6 +281,12 @@ rte_validate(rte *e)
return 1; return 1;
} }
/**
* rte_free - delete a &rte
* @e: &rte to be deleted
*
* rte_free() deletes the given &rte from the routing table it's linked to.
*/
void void
rte_free(rte *e) rte_free(rte *e)
{ {
...@@ -375,6 +419,26 @@ rte_update_unlock(void) ...@@ -375,6 +419,26 @@ rte_update_unlock(void)
lp_flush(rte_update_pool); lp_flush(rte_update_pool);
} }
/**
* rte_update - enter a new update to a routing table
* @table: table to be updated
* @net: network node
* @p: protocol submitting the update
* @new: a &rte representing the new route or %NULL for route removal.
*
* 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 uncached with @aflags set
* to zero or a cached one using rta_lookup(); in this case please note that
* you need to increase the use count of the attributes yourself by calling
* rta_clone()), call rte_get_temp() to obtain a temporary &rte, fill in all
* the appropriate data and finally submit the new &rte by calling rte_update().
*
* rte_update() will automatically find the old route defined by the protocol @p
* for network @n, replace it by the new one (or removing it if @new is %NULL),
* recalculate the optimal route for this destination and finally broadcast
* the change (if any) to all routing protocols.
*/
void void
rte_update(rtable *table, net *net, struct proto *p, rte *new) rte_update(rtable *table, net *net, struct proto *p, rte *new)
{ {
...@@ -431,6 +495,12 @@ rte_discard(rtable *t, rte *old) /* Non-filtered route deletion, used during gar ...@@ -431,6 +495,12 @@ rte_discard(rtable *t, rte *old) /* Non-filtered route deletion, used during gar
rte_update_unlock(); rte_update_unlock();
} }
/**
* rte_dump - dump a route
* @e: &rte to be dumped
*
* This functions dumps contents of a &rte to debug output.
*/
void void
rte_dump(rte *e) rte_dump(rte *e)
{ {
...@@ -446,6 +516,12 @@ rte_dump(rte *e) ...@@ -446,6 +516,12 @@ rte_dump(rte *e)
debug("\n"); debug("\n");
} }
/**
* rt_dump - dump a routing table
* @t: routing table to be dumped
*
* This function dumps contents of a given routing table to debug output.
*/
void void
rt_dump(rtable *t) rt_dump(rtable *t)
{ {
...@@ -469,6 +545,11 @@ rt_dump(rtable *t) ...@@ -469,6 +545,11 @@ rt_dump(rtable *t)
debug("\n"); debug("\n");
} }
/**
* rt_dump_all - dump all routing tables
*
* This function dumps contents of all routing tables to debug output.
*/
void void
rt_dump_all(void) rt_dump_all(void)
{ {
...@@ -505,6 +586,12 @@ rt_setup(pool *p, rtable *t, char *name, struct rtable_config *cf) ...@@ -505,6 +586,12 @@ rt_setup(pool *p, rtable *t, char *name, struct rtable_config *cf)
} }
} }
/**
* rt_init - initialize routing tables
*
* This function is called during BIRD startup. It initializes the
* routing table module.
*/
void void
rt_init(void) rt_init(void)
{ {
...@@ -515,6 +602,14 @@ rt_init(void) ...@@ -515,6 +602,14 @@ rt_init(void)
init_list(&routing_tables); init_list(&routing_tables);
} }
/**
* rt_prune - prune a routing table
* @tab: routing table to be pruned
*
* This function is called whenever a protocol shuts down. It scans
* the routing table and removes all routes belonging to inactive
* protocols and also stale network entries.
*/
void void
rt_prune(rtable *tab) rt_prune(rtable *tab)
{ {
...@@ -558,6 +653,11 @@ again: ...@@ -558,6 +653,11 @@ again:
tab->gc_time = now; tab->gc_time = now;
} }
/**
* rt_prune_all - prune all routing tables
*
* This function calls rt_prune() for all known routing tables.
*/
void void
rt_prune_all(void) rt_prune_all(void)
{ {
...@@ -589,12 +689,28 @@ rt_preconfig(struct config *c) ...@@ -589,12 +689,28 @@ rt_preconfig(struct config *c)
c->master_rtc = rt_new_table(s); c->master_rtc = rt_new_table(s);
} }
/**
* rt_lock_table - lock a routing table
* @r: routing table to be locked
*
* 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.
*/
void void
rt_lock_table(rtable *r) rt_lock_table(rtable *r)
{ {
r->use_count++; r->use_count++;
} }
/**
* rt_unlock_table - unlock a routing table
* @r: routing table to be unlocked
*
* Unlock a routing table formerly locked by rt_lock_table(),
* that is decrease its use count and delete it if it's scheduled
* for deletion by configuration changes.
*/
void void
rt_unlock_table(rtable *r) rt_unlock_table(rtable *r)
{ {
...@@ -609,6 +725,18 @@ rt_unlock_table(rtable *r) ...@@ -609,6 +725,18 @@ rt_unlock_table(rtable *r)
} }
} }
/**
* rt_commit - commit new routing table configuration
* @new: new configuration
* @old: original configuration or %NULL if it's boot time config
*
* Scan differences between @old and @new configuration and modify
* the routing tables according to these changes. If @new defines a
* previously unknown table, create it, if it omits a table existing
* in @old, schedule it for deletion (it gets deleted when all protocols
* disconnect from it by calling rt_unlock_table()), if it exists
* in both configurations, leave it unchanged.
*/
void void
rt_commit(struct config *new, struct config *old) rt_commit(struct config *new, struct config *old)
{ {
...@@ -655,6 +783,15 @@ rt_commit(struct config *new, struct config *old) ...@@ -655,6 +783,15 @@ rt_commit(struct config *new, struct config *old)
DBG("\tdone\n"); DBG("\tdone\n");
} }
/**
* rt_feed_baby - advertise routes to a new protocol
* @p: protocol to be fed
*
* 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.)
*/
int int
rt_feed_baby(struct proto *p) rt_feed_baby(struct proto *p)
{ {
...@@ -713,6 +850,14 @@ next_hook: ...@@ -713,6 +850,14 @@ next_hook:
goto again; goto again;
} }
/**
* rt_feed_baby_abort - abort protocol feeding
* @p: protocol
*
* This function is called by the protocol code when the protocol
* stops or ceases to exist before the last iteration of rt_feed_baby()
* has finished.
*/
void void
rt_feed_baby_abort(struct proto *p) rt_feed_baby_abort(struct proto *p)
{ {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment