Commit 1f495723 authored by Martin Mareš's avatar Martin Mareš

Documented.

parent ce4aca09
H Core
S neighbor.c
#S cli.c
#S iface.c
S locks.c
#S proto.c
#S rt-attr.c
#S rt-dev.c
S rt-fib.c
#S rt-table.c
......@@ -6,6 +6,28 @@
* Can be freely distributed and used under the terms of the GNU GPL.
*/
/**
* DOC: Object locks
*
* The lock module provides a simple mechanism for avoiding conflicts between
* various protocols which would like to use a single physical resource (for
* example a network port). It would be easy to say that such collisions can
* occur only when the user specifies an invalid configuration and therefore
* he deserves to get what he has asked for, but unfortunately they can also
* arise legitimately when the daemon is reconfigured and there exists (although
* for a short time period only) an old protocol being shut down and a new one
* willing to start up on the same interface.
*
* The solution is very simple: when any protocol wishes to use a network port
* or some other non-shareable resource, it asks the core to lock it and doesn't
* use the resource until it's notified that it has acquired the lock.
*
* Object locks are represented by &object_lock which is in turn a kind of
* resource. Lockable resources are uniquely determined by resource type
* (%OBJLOCK_UDP for a UDP port etc.), IP address (usually a broadcast or
* multicast address the port is bound to), port number and interface.
*/
#undef LOCAL_DEBUG
#include "nest/bird.h"
......@@ -78,6 +100,14 @@ static struct resclass olock_class = {
olock_dump
};
/**
* olock_new - create an object lock
* @p: resource pool to create the lock in.
*
* The olock_new() function creates a new resource of type &object_lock
* and returns a pointer to it. After filling in the structure, the caller
* should call olock_acquire() to do the real locking.
*/
struct object_lock *
olock_new(pool *p)
{
......@@ -88,6 +118,17 @@ olock_new(pool *p)
return l;
}
/**
* olock_acquire - acquire a lock
* @l: the lock to acquire
*
* This function attempts to acquire exclusive access to the non-shareable
* resource described by the lock @l. It returns immediately, but as soon
* as the resource becomes available, it calls the hook() function set up
* by the caller.
*
* When you want to release the resource, just rfree() the lock.
*/
void
olock_acquire(struct object_lock *l)
{
......@@ -134,6 +175,12 @@ olock_run_event(void *unused)
}
}
/**
* olock_init - initialize the object lock mechanism
*
* This function is called during BIRD startup. It initializes
* all the internal data structures of the lock module.
*/
void
olock_init(void)
{
......
......@@ -6,6 +6,37 @@
* Can be freely distributed and used under the terms of the GNU GPL.
*/
/**
* DOC: Neighbor cache
*
* Most routing protocols need to associate their internal state data with
* neighboring routers, check whether an address given as the next hop
* attribute of a route is really an address of a directly connected host
* and which interface is it connected through. Also, they often need to
* be notified when a neighbor ceases to exist or when their long awaited
* neighbor becomes connected. The neighbor cache is there to solve all
* these problems.
*
* The neighbor cache maintains a collection of neighbor entries. Each
* entry represents one IP address corresponding to either our directly
* connected neighbor or our own end of the link (when the scope of the
* address is set to %SCOPE_HOST) together with data belonging to a
* single protocol.
*
* Active entries represent known neighbors and are stored in a hash
* table (to allow fast retrieval based on 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 %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 becomes up.
*
* When a neighbor event occurs (a neighbor gets disconnected or a sticky
* inactive neighbor becomes connected), the protocol hook neigh_notify()
* is called to advertise the change.
*/
#undef LOCAL_DEBUG
#include "nest/bird.h"
......@@ -54,6 +85,21 @@ if_connected(ip_addr *a, struct iface *i) /* -1=error, 1=match, 0=no match */
return -1;
}
/**
* neigh_find - find or create a neighbor entry.
* @p: protocol which asks for the entry.
* @a: pointer to IP address of the node to be searched for.
* @flags: 0 or %NEF_STICKY if you want to create a sticky entry.
*
* 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 *@a is not a valid unicast
* IP address, neigh_find() returns %NULL.
*/
neighbor *
neigh_find(struct proto *p, ip_addr *a, unsigned flags)
{
......@@ -104,6 +150,13 @@ neigh_find(struct proto *p, ip_addr *a, unsigned flags)
return n;
}
/**
* neigh_dump - dump specified neighbor entry.
* @n: the entry to dump
*
* This functions dumps the contents of a given neighbor entry
* to debug output.
*/
void
neigh_dump(neighbor *n)
{
......@@ -118,6 +171,12 @@ neigh_dump(neighbor *n)
debug("\n");
}
/**
* neigh_dump_all - dump all neighbor entries.
*
* This function dumps the contents of the neighbor cache to
* debug output.
*/
void
neigh_dump_all(void)
{
......@@ -133,6 +192,15 @@ neigh_dump_all(void)
debug("\n");
}
/**
* neigh_if_up: notify neighbor cache about interface up event
* @i: interface in question
*
* Tell the neighbor cache that a new interface became up.
*
* The neighbor cache wakes up all inactive sticky neighbors with
* addresses belonging to prefixes of the interface @i.
*/
void
neigh_if_up(struct iface *i)
{
......@@ -153,6 +221,15 @@ neigh_if_up(struct iface *i)
}
}
/**
* neigh_if_down - notify neighbor cache about interface down event
* @i: the interface in question
*
* Notify the neighbor cache that an interface has ceased to exist.
*
* It causes all entries belonging to neighbors connected to this interface
* to be flushed.
*/
void
neigh_if_down(struct iface *i)
{
......@@ -185,6 +262,13 @@ neigh_prune_one(neighbor *n)
sl_free(neigh_slab, n);
}
/**
* neigh_prune - prune neighbor cache
*
* 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.
*/
void
neigh_prune(void)
{
......@@ -200,6 +284,13 @@ neigh_prune(void)
neigh_prune_one(n);
}
/**
* neigh_init - initialize the neighbor cache.
* @if_pool: resource pool to be used for neighbor entries.
*
* This function is called during BIRD startup to initialize
* the neighbor cache module.
*/
void
neigh_init(pool *if_pool)
{
......
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