Doc in neighbor.c and some tiny changes related to.

7 files changed, 88 insertions, 18 deletions

diff --git a/proto/ospf/iface.c b/proto/ospf/iface.c
index e96ca73..4d20507 100644
--- a/proto/ospf/iface.c
+++ b/proto/ospf/iface.c
@@ -158,14 +158,14 @@ ospf_int_sm(struct ospf_iface *ifa, int event)
     case ISM_WAITF:
       if(ifa->state==OSPF_IS_WAITING)
       {
-        bdr_election(ifa ,p);
+        bdr_election(ifa);
       }
       break;
     case ISM_NEICH:
       if((ifa->state==OSPF_IS_DROTHER) || (ifa->state==OSPF_IS_DR) ||
         (ifa->state==OSPF_IS_BACKUP))
       {
-        bdr_election(ifa ,p);
+        bdr_election(ifa);
         schedule_rt_lsa(ifa->oa);
       }
       break;
diff --git a/proto/ospf/neighbor.c b/proto/ospf/neighbor.c
index ef674a1..ddc2e62 100644
--- a/proto/ospf/neighbor.c
+++ b/proto/ospf/neighbor.c
@@ -1,7 +1,7 @@
 /*
  *	BIRD -- OSPF
  *
- *	(c) 1999 Ondrej Filip <feela@network.cz>
+ *	(c) 1999 - 2000 Ondrej Filip <feela@network.cz>
  *
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
@@ -22,6 +22,15 @@ const char *ospf_inm[]={ "hello received", "neighbor start", "2-way received",
   "adjacency ok?", "sequence mismatch", "1-way received", "kill neighbor",
   "inactivity timer", "line down" };
 
+/**
+ * neigh_chstate - handles changes related to new or lod state of neighbor
+ * @n: OSPF neighbor
+ * @state: new state
+ *
+ * Many actions has to be taken acording to state change of neighbor. It
+ * starts rxmt timers, call interface state machine etc.
+ */
+
 void
 neigh_chstate(struct ospf_neighbor *n, u8 state)
 {
@@ -49,14 +58,14 @@ neigh_chstate(struct ospf_neighbor *n, u8 state)
     {
       ifa->fadj--;
       schedule_rt_lsa(ifa->oa);
-      originate_net_lsa(ifa,po);
+      originate_net_lsa(ifa);
     }
   
     if(state==NEIGHBOR_FULL)	/* Increase number of adjacencies */
     {
       ifa->fadj++;
       schedule_rt_lsa(ifa->oa);
-      originate_net_lsa(ifa,po);
+      originate_net_lsa(ifa);
     }
     if(oldstate>=NEIGHBOR_EXSTART && state<NEIGHBOR_EXSTART)
     {
@@ -203,9 +212,20 @@ can_do_adj(struct ospf_neighbor *n)
   return i;
 }
 
+/**
+ * ospf_neigh_sm - ospf neighbor state machine
+ * @n: neighor
+ * @event: actual event
+ *
+ * This part implements neighbor state machine as described in 10.3 of
+ * RFC 2328. the only difference is that state %NEIGHBOR_ATTEMPT is not
+ * used. We discover neighbors on nonbroadcast networks using the
+ * same ways as on broadcast networks. The only difference is in
+ * sending hello packets. These are send to IPs listed in
+ * @ospf_iface->nbma_list .
+ */
 void
 ospf_neigh_sm(struct ospf_neighbor *n, int event)
-	/* Interface state machine */
 {
   struct proto *p=(struct proto *)(n->ifa->proto);
   struct proto_ospf *po=n->ifa->proto;
@@ -217,7 +237,7 @@ ospf_neigh_sm(struct ospf_neighbor *n, int event)
   {
     case INM_START:
       neigh_chstate(n,NEIGHBOR_ATTEMPT);
-      /* FIXME No NBMA now */
+      /* NBMA are used different way */
       break;
     case INM_HELLOREC:
       switch(n->state)
@@ -298,14 +318,22 @@ ospf_neigh_sm(struct ospf_neighbor *n, int event)
   }
 }
 
+/**
+ * bdr_election - (Backup) Designed Router election
+ * @ifa: actual interface
+ *
+ * When wait time fires, it time to elect (Backup) Designed Router.
+ * Structure describing me is added to this list so every electing router
+ * has the same list. Backup Designed Router is elected before Designed
+ * Router. This process is described in 9.4 of RFC 2328.
+ */
 void
-bdr_election(struct ospf_iface *ifa, struct proto *p)
+bdr_election(struct ospf_iface *ifa)
 {
   struct ospf_neighbor *neigh,*ndr,*nbdr,me,*tmp;
   u32 myid, ndrid, nbdrid;
   int doadj;
-
-  p=(struct proto *)(ifa->proto);
+  struct proto *p=&ifa->proto->proto;
 
   DBG("%s: (B)DR election.\n",p->name);
 
@@ -323,7 +351,7 @@ bdr_election(struct ospf_iface *ifa, struct proto *p)
   nbdr=electbdr(ifa->neigh_list);
   ndr=electdr(ifa->neigh_list);
 
-  if(ndr==NULL) ndr=nbdr;		/* FIXME is this correct? */
+  if(ndr==NULL) ndr=nbdr;
 
   if(((ifa->drid==myid) && (ndr!=&me))
     || ((ifa->drid!=myid) && (ndr==&me))
@@ -511,7 +539,6 @@ ospf_sh_neigh_info(struct ospf_neighbor *n)
    if(n->rid==ifa->bdrid) pos="bdr  ";
    if(n->ifa->type==OSPF_IT_PTP) pos="ptp  ";
 
-
    cli_msg(-1013,"%-18I\t%3u\t%s/%s\t%-5s\t%-18I\t%-10s",n->rid, n->priority,
      ospf_ns[n->state], pos, etime, n->ip,ifa->iface->name);
 }
diff --git a/proto/ospf/neighbor.h b/proto/ospf/neighbor.h
index 4f2a4c9..f68c69a 100644
--- a/proto/ospf/neighbor.h
+++ b/proto/ospf/neighbor.h
@@ -1,7 +1,7 @@
 /*
  *      BIRD -- OSPF
  *
- *      (c) 1999 Ondrej Filip <feela@network.cz>
+ *      (c) 1999 - 2000 Ondrej Filip <feela@network.cz>
  *
  *      Can be freely distributed and used under the terms of the GNU GPL.
  *
@@ -16,7 +16,7 @@ struct ospf_neighbor *electdr(list nl);
 int can_do_adj(struct ospf_neighbor *n);
 void tryadj(struct ospf_neighbor *n, struct proto *p);
 void ospf_neigh_sm(struct ospf_neighbor *n, int event);
-void bdr_election(struct ospf_iface *ifa, struct proto *p);
+void bdr_election(struct ospf_iface *ifa);
 struct ospf_neighbor *find_neigh(struct ospf_iface *ifa, u32 rid);
 struct ospf_neighbor *find_neigh_noifa(struct proto_ospf *po, u32 rid);
 struct ospf_area *ospf_find_area(struct proto_ospf *po, u32 aid);
diff --git a/proto/ospf/ospf.c b/proto/ospf/ospf.c
index 6527c8c..af9e586 100644
--- a/proto/ospf/ospf.c
+++ b/proto/ospf/ospf.c
@@ -1,7 +1,7 @@
 /*
  *	BIRD -- OSPF
  *
- *	(c) 1999-2000 Ondrej Filip <feela@network.cz>
+ *	(c) 1999 - 2000 Ondrej Filip <feela@network.cz>
  *
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
diff --git a/proto/ospf/ospf.h b/proto/ospf/ospf.h
index 699ab2a..3694cda 100644
--- a/proto/ospf/ospf.h
+++ b/proto/ospf/ospf.h
@@ -1,7 +1,7 @@
 /*
  *	BIRD -- OSPF
  *
- *	(c) 1999-2000 Ondrej Filip <feela@network.cz>
+ *	(c) 1999 - 2000 Ondrej Filip <feela@network.cz>
  *
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
diff --git a/proto/ospf/topology.c b/proto/ospf/topology.c
index 607583a..bf90899 100644
--- a/proto/ospf/topology.c
+++ b/proto/ospf/topology.c
@@ -169,6 +169,15 @@ addifa_rtlsa(struct ospf_iface *ifa)
   else ifa->oa=oa;
 }
 
+/**
+ * originate_rt_lsa - build new instance of router LSA
+ * @oa: ospf_area which is LSA built to
+ *
+ * It builds router LSA walking through all OSPF interfaces in
+ * specified OSPF area. This function is mostly called from
+ * area_disp(). Builds new LSA, increases sequence number (if old
+ * instance exists) and sets age of LSA to zero.
+ */
 void
 originate_rt_lsa(struct ospf_area *oa)
 {
@@ -231,9 +240,19 @@ originate_net_lsa_body(struct ospf_iface *ifa, u16 *length,
   return net;
 }
 
+/**
+ * originate_net_lsa - originates of deletes network LSA
+ * @ifa: interface which is LSA originated for
+ *
+ * Interface counts number of adjacent neighbor. If this number is
+ * lower then one or interface is not in state %OSPF_IS_DR it deletes
+ * and premature ages instance of network LSA for specified interface.
+ * In other case, new instance of network LSA is originated.
+ */
 void
-originate_net_lsa(struct ospf_iface *ifa, struct proto_ospf *po)
+originate_net_lsa(struct ospf_iface *ifa)
 {
+  struct proto_ospf *po=ifa->proto;
   struct ospf_lsa_header lsa;
   u32 rtid=po->proto.cf->global->router_id;
   struct top_hash_entry *en;
@@ -247,6 +266,8 @@ originate_net_lsa(struct ospf_iface *ifa, struct proto_ospf *po)
   {
     if(ifa->nlsa==NULL) return;
 
+    OSPF_TRACE(D_EVENTS, "Deleting Net lsa for iface \"%s\".",
+      ifa->iface->name);
     ifa->nlsa->lsa.sn+=1;
     ifa->nlsa->lsa.age=LSA_MAXAGE;
     flood_lsa(NULL,NULL,&ifa->nlsa->lsa,po,NULL,ifa->oa,0);
@@ -257,6 +278,9 @@ originate_net_lsa(struct ospf_iface *ifa, struct proto_ospf *po)
     return ;
   }
 
+  OSPF_TRACE(D_EVENTS, "Originating Net lsa for iface \"%s\".",
+    ifa->iface->name);
+
   lsa.age=0;
   lsa.id=ipa_to_u32(ifa->iface->addr->ip);
   lsa.type=LSA_T_NET;
@@ -317,6 +341,18 @@ originate_ext_lsa_body(net *n, rte *e, struct proto_ospf *po, struct ea_list *at
   return ext;
 }
 
+/**
+ * originate_ext_lsa - new route recived from nest and filters
+ * @n: network prefix and mask
+ * @e: rte
+ * @po: current instance of OSPF
+ * @attrs: list of extended attributes
+ *
+ * If I receive message that new route is installed, I try to originate an
+ * external LSA. LSA header of such LSA does not contain information about
+ * prefix lenght, so if I have to originate multiple LSAs for route with
+ * different prefixes I try to increment prefix id to find a "free" one.
+ */
 void
 originate_ext_lsa(net *n, rte *e, struct proto_ospf *po, struct ea_list *attrs)
 {
@@ -417,6 +453,13 @@ return (ospf_top_hash_u32(lsaid) + ospf_top_hash_u32((type==LSA_T_NET) ? lsaid :
 #endif
 }
 
+/**
+ * ospf_top_new - allocated new topology database
+ * @p: current instance of OSPF
+ *
+ * This dynamically hashed structure is often used for keeping LSAs. Mainly
+ * its used in @ospf_area structute.
+ */
 struct top_graph *
 ospf_top_new(struct proto_ospf *p)
 {
diff --git a/proto/ospf/topology.h b/proto/ospf/topology.h
index de04cae..3a47508 100644
--- a/proto/ospf/topology.h
+++ b/proto/ospf/topology.h
@@ -47,7 +47,7 @@ struct top_hash_entry *ospf_hash_get(struct top_graph *, u32 lsa, u32 rtr, u32 t
 void ospf_hash_delete(struct top_graph *, struct top_hash_entry *);
 void addifa_rtlsa(struct ospf_iface *ifa);
 void originate_rt_lsa(struct ospf_area *oa);
-void originate_net_lsa(struct ospf_iface *ifa,struct proto_ospf *po);
+void originate_net_lsa(struct ospf_iface *ifa);
 int can_flush_lsa(struct ospf_area *oa);
 void originate_ext_lsa(net *n, rte *e, struct proto_ospf *po, struct ea_list *attrs);