Updates to both programmers and users doc

4 files changed, 116 insertions, 27 deletions

diff --git a/doc/bird.sgml b/doc/bird.sgml
index 1dc2bee..2adf9b5 100644
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -124,7 +124,15 @@ there are more entries with same preference and they are from same
 protocol, protocol decides (typically according to metrics). If not,
 internal ordering is used to decide. You can
 get list of route attributes in "Route attributes" section in
-filters. Filters can alter routes passed between routing tables and
+filters. 
+
+<p>Protocols are connected to routing tables using filters. Routes
+that come from network go to the protocol, it then passes them to
+filters, if import filter accepts route, it gets to main routing
+table. It is then broadcasted to all other protocols (filtered through
+their export filters), which typically send it to the network.
+
+Filters can alter routes passed between routing tables and
 protocols.
 
 <sect>Installing BIRD
@@ -142,7 +150,12 @@ system, installing BIRD should be as easy as:
 
 <p>You can use <tt>./configure --help</tt> to get list of configure
 options. Most important (and not easily guessed) option is
-<tt/--enable-ipv6/, which enables IPv6 support.
+<tt/--enable-ipv6/, which enables IPv6 support. You can use
+<tt/--with-protocols=/ to produce slightly smaller BIRD, and
+<tt/--prefix=/ to install bird somewhere else than
+<file>/usr/local</file>.
+
+<sect>Running bird
 
 <p>You can pass several command-line options to bird:
 
@@ -168,7 +181,7 @@ options. Most important (and not easily guessed) option is
 <tt/-c/ command line option is given). Configuration may be changed on user request: if you modify
 config file and then signal BIRD with SIGHUP, it will adjust to new
 config. Then there's BIRD client,
-which allows you to talk with BIRD in more extensive way than just telling it to reconfigure. BIRD
+which allows you to talk with BIRD in extensive way. (Of course you can tell BIRD to reconfigure from BIRDC, you can also tell it to shut down, dump various info etc.). BIRD
 writes messages about its work to log files or syslog (according to config).
 
 <p>In config, everything on a line after <cf/#/ or inside <cf>/*
@@ -230,8 +243,8 @@ protocol rip {
 	about configuring protocols in their own chapters. You can run more than one instance of
 	most protocols (like rip or bgp).
 
-	<tag>define constant = (<m/expression/)|<m/number/</tag> define constant. You can use it later in every place
-	you could use simple integer.
+	<tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/ip address/</tag> define constant. You can use it later in every place
+	you could use simple integer/ip address.
 
 	<tag>router id <m/IPv4 address/</tag> set router id. Router id needs to be world-wide
 	unique. It is usually one of router's IPv4 addresses.
@@ -468,8 +481,7 @@ incompatible with each other (that is to prevent you from shooting in the foot).
 <cf/(a=b, a!=b, a&lt;b, a&gt;=b)/. Special operators include <cf/&tilde;/ for "in" operation. In operation can be
 used on element and set of that elements, or on ip and prefix, or on
 prefix and prefix or on bgppath and bgpmask or on pair and clist. Its result
-is true if element is in given set or if ip address is inside given prefix. Operator <cf/=/ is used to assign value
-to variable. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/>).
+is true if element is in given set or if ip address is inside given prefix. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/>).
 
 <sect>Control structures
 
@@ -531,14 +543,16 @@ defined using <cf>defined( <m>attribute</m> )</cf> syntax.
 	FIXME!
 </descrip>
 
-<p>Plus, there are protocol-specific attributes, which are described in protocol sections.
+<p>Then there are protocol-specific attributes, which are described in protocol sections.
 
-<sect>Utility functions
+<sect>Statements
 
-<p>There are few functions you might find convenient to use:
+<p>Following statements are supported:
 
 <descrip>
-	<tag>accept</tag> accept this route
+	<tag><m/variable/ = <m/expr/</tag> set variable to give value.
+
+	<tag>accept [ <m/expr/ ]</tag> accept this route, possibly printing expr
 
 	<tag>reject</tag> reject this route
 
diff --git a/filter/filter.c b/filter/filter.c
index c12435c..5c50b9a 100644
--- a/filter/filter.c
+++ b/filter/filter.c
@@ -70,7 +70,9 @@ pm_path_compare(struct f_path_mask *m1, struct f_path_mask *m2)
   }
 }
 
-/* Compare two values, returns -1, 0, 1 compared, ERROR 999 */
+/**
+ * val_compare - compare two values, returns -1, 0, 1 on <, =, > and 999 on error */
+ */
 int
 val_compare(struct f_val v1, struct f_val v2)
 {
@@ -103,6 +105,9 @@ val_compare(struct f_val v1, struct f_val v2)
   }
 }
 
+/**
+ * val_simple_in_range - check if @v1 ~ @v2 for everything except sets
+ */ 
 int
 val_simple_in_range(struct f_val v1, struct f_val v2)
 {
@@ -134,6 +139,9 @@ val_simple_in_range(struct f_val v1, struct f_val v2)
   return CMP_ERROR;
 }
 
+/**
+ * val_in_range - check if @v1 ~ @v2
+ */
 int
 val_in_range(struct f_val v1, struct f_val v2)
 {
@@ -175,6 +183,9 @@ tree_print(struct f_tree *t)
   debug( "] " );
 }
 
+/**
+ * val_print - format filter value
+ */
 void
 val_print(struct f_val v)
 {
@@ -207,6 +218,9 @@ static struct ea_list **f_tmp_attrs;
 static int f_flags;
 static rta *f_rta_copy;
 
+/**
+ * rta_cow - prepare rta for modification by filter
+ */
 void
 rta_cow(void)
 {
@@ -239,6 +253,13 @@ rta_cow(void)
                   if (v1.type != v2.type) \
 		    runtime( "Can not operate with values of incompatible types" );
 
+/**
+ * interpret
+ * @what: filter to interrpret
+ *
+ * Interrpret given tree of filter instructions. This is core function
+ * of filter system and does all the hard work.
+ */
 static struct f_val
 interpret(struct f_inst *what)
 {
@@ -660,6 +681,9 @@ interpret(struct f_inst *what)
 
 #define A2_SAME if (f1->a2.i != f2->a2.i) return 0;
 
+/**
+ * i_same - function that does real comparing of instruction trees, you should call filter_same from outside
+ */
 int
 i_same(struct f_inst *f1, struct f_inst *f2)
 {
diff --git a/proto/rip/auth.c b/proto/rip/auth.c
index 994021e..f1a3204 100644
--- a/proto/rip/auth.c
+++ b/proto/rip/auth.c
@@ -26,7 +26,9 @@
 
 #define PACKETLEN(num) (num * sizeof(struct rip_block) + sizeof(struct rip_packet_heading))
 
-/* 1 == failed, 0 == ok */
+/**
+ * rip_incoming_authentication - check authentication of incomming packet and return 1 if there's problem.
+ */
 int
 rip_incoming_authentication( struct proto *p, struct rip_block_auth *block, struct rip_packet *packet, int num, ip_addr whotoldme )
 {
@@ -108,6 +110,10 @@ rip_incoming_authentication( struct proto *p, struct rip_block_auth *block, stru
   return 0;
 }
 
+/**
+ * rip_outgoing_authentication - append authentication information to the packet.
+ * %num: number of rip_blocks already in packets. This function returns size of packet to send.
+ */
 int
 rip_outgoing_authentication( struct proto *p, struct rip_block_auth *block, struct rip_packet *packet, int num )
 {
diff --git a/proto/rip/rip.c b/proto/rip/rip.c
index 0256528..698f0e2 100644
--- a/proto/rip/rip.c
+++ b/proto/rip/rip.c
@@ -40,7 +40,6 @@
  * we look for any changed routes and broadcast them.
  */
 
-
 #undef LOCAL_DEBUG
 
 #include "nest/bird.h"
@@ -65,8 +64,10 @@ static struct rip_interface *new_iface(struct proto *p, struct iface *new, unsig
 
 #define P_NAME p->name
 
-/*
- * Output processing
+/** 
+ * DOC: Output processing
+ *
+ * This part is responsible for getting packets out to the network.
  */
 
 static void
@@ -77,6 +78,15 @@ rip_tx_err( sock *s, int err )
   log( L_ERR "%s: Unexpected error at rip transmit: %M", P_NAME, err );
 }
 
+/**
+ * rip_tx_prepare:
+ * @e: rip entry that needs to be translated to form suitable for network
+ * @b: block to be filled
+ *
+ * Fill one rip block with info that needs to go to the network. Handle
+ * nexthop and split horizont correctly. (Next hop is ignored for IPv6,
+ * that could be fixed but it is not real problem).
+ */
 static int
 rip_tx_prepare(struct proto *p, ip_addr daddr, struct rip_block *b, struct rip_entry *e, struct rip_interface *rif, int pos )
 {
@@ -106,6 +116,9 @@ rip_tx_prepare(struct proto *p, ip_addr daddr, struct rip_block *b, struct rip_e
   return pos+1;
 }
 
+/**
+ * rip_tx - send one rip packet to the network
+ */
 static void
 rip_tx( sock *s )
 {
@@ -181,6 +194,11 @@ done:
   return;
 }
 
+/** 
+ * rip_sendto - send whole routing table to selected destination
+ * @rif: interface to use. Notice that we lock interface so that at
+ * most one send to one interface is done.
+ */
 static void
 rip_sendto( struct proto *p, ip_addr daddr, int dport, struct rip_interface *rif )
 {
@@ -204,12 +222,6 @@ rip_sendto( struct proto *p, ip_addr daddr, int dport, struct rip_interface *rif
   c->daddr = daddr;
   if (c->rif->sock->data != rif)
     bug("not enough send magic");
-#if 0
-  if (sk_open(c->send)<0) {
-    log( L_ERR "%s Could not open socket for data send to %I:%d on %s", P_NAME, daddr, dport, rif->iface->name );
-    return;
-  }
-#endif
 
   c->done = 0;
   FIB_ITERATE_INIT( &c->iter, &P->rtable );
@@ -233,8 +245,10 @@ find_interface(struct proto *p, struct iface *what)
   return NULL;
 }
 
-/*
- * Input processing
+/**
+ * DOC: Input processing
+ *
+ * This part is responsible for any updates that come from network 
  */
 
 static void
@@ -247,7 +261,14 @@ rip_rte_update_if_better(rtable *tab, net *net, struct proto *p, rte *new)
     rte_update(tab, net, p, new);
 }
 
-/* Let main routing table know about our new entry */
+/**
+ * advertise_entry - let main routing table know about our new entry
+ * @b: entry in network format
+ *
+ * This basically translates @b to format used by bird core and feeds
+ * bird core with this route. Notice that we do not store info anywhere
+ * in our data structures: we'll do that when core notifies us back. 
+ */
 static void
 advertise_entry( struct proto *p, struct rip_block *b, ip_addr whotoldme )
 {
@@ -312,6 +333,9 @@ advertise_entry( struct proto *p, struct rip_block *b, ip_addr whotoldme )
   DBG( "done\n" );
 }
 
+/**
+ * process_block - do some basic check and pass block to advertise_entry
+ */
 static void
 process_block( struct proto *p, struct rip_block *block, ip_addr whotoldme )
 {
@@ -335,6 +359,9 @@ process_block( struct proto *p, struct rip_block *block, ip_addr whotoldme )
 
 #define BAD( x ) { log( L_REMOTE "%s: " x, P_NAME ); return 1; }
 
+/**
+ * rip_process_packet - this is main routine for incoming packets.
+ */
 static int
 rip_process_packet( struct proto *p, struct rip_packet *packet, int num, ip_addr whotoldme, int port )
 {
@@ -402,6 +429,9 @@ rip_process_packet( struct proto *p, struct rip_packet *packet, int num, ip_addr
   return 0;
 }
 
+/**
+ * rip_rx - Receive hook: do basic checks and pass packet to rip_process_packet
+ */
 static int
 rip_rx(sock *s, int size)
 {
@@ -431,8 +461,8 @@ rip_rx(sock *s, int size)
   return 1;
 }
 
-/*
- * Interface to rest of bird
+/**
+ * DOC: Interface to bird core
  */
 
 static void
@@ -443,6 +473,9 @@ rip_dump_entry( struct rip_entry *e )
   debug( "\n" );
 }
 
+/**
+ * rip_timer - broadcast routing tables periodically (using rip_tx) and kill routes that are too old
+ */
 static void
 rip_timer(timer *t)
 {
@@ -771,6 +804,10 @@ rip_store_tmp_attrs(struct rte *rt, struct ea_list *attrs)
   rt->u.rip.metric = ea_get_int(attrs, EA_RIP_METRIC, 1);
 }
 
+/**
+ * rip_rt_notify - core tells us about new route (possibly our
+ * own), so store it into our data structures. 
+ */
 static void
 rip_rt_notify(struct proto *p, struct network *net, struct rte *new, struct rte *old, struct ea_list *attrs)
 {
@@ -839,6 +876,11 @@ rip_rte_better(struct rte *new, struct rte *old)
   return 0;
 }
 
+/**
+ * rip_rte_insert - we maintain linked list of "our" entries in main
+ * routing table, so that we can timeout them correctly. rip_timer
+ * walks the list.
+ */
 static void
 rip_rte_insert(net *net, rte *rte)
 {
@@ -849,6 +891,9 @@ rip_rte_insert(net *net, rte *rte)
   add_head( &P->garbage, &rte->u.rip.garbage );
 }
 
+/**
+ * rip_rte_remove - link list maintenance
+ */
 static void
 rip_rte_remove(net *net, rte *rte)
 {