summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMartin Mares <mj@ucw.cz>2000-06-01 18:16:49 +0200
committerMartin Mares <mj@ucw.cz>2000-06-01 18:16:49 +0200
commit1f495723c355b66383ab391fdba84aae7e9226eb (patch)
tree876449fff1a3de1e5ddfa1388281179f46a6756c
parentce4aca093a267da3dcd07b25f4390d393fd3c259 (diff)
downloadbird-1f495723c355b66383ab391fdba84aae7e9226eb.tar
bird-1f495723c355b66383ab391fdba84aae7e9226eb.zip
Documented.
-rw-r--r--nest/Doc9
-rw-r--r--nest/locks.c47
-rw-r--r--nest/neighbor.c91
3 files changed, 147 insertions, 0 deletions
diff --git a/nest/Doc b/nest/Doc
index 752067a..57a3c83 100644
--- a/nest/Doc
+++ b/nest/Doc
@@ -1 +1,10 @@
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
diff --git a/nest/locks.c b/nest/locks.c
index 19a5df0..c1f7331 100644
--- a/nest/locks.c
+++ b/nest/locks.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)
{
diff --git a/nest/neighbor.c b/nest/neighbor.c
index 0c7a4ae..89c19ba 100644
--- a/nest/neighbor.c
+++ b/nest/neighbor.c
@@ -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)
{