pimd: added comments for upstream and channel_oil new values

Added comments which explains the new values for existing fields
and new fields in the upstream and channel_oil data structure.

Following are the summary of the behaviour change in PIM code.

Scenario 1 : RP doesn’t exist/RP not reachable
Event: Join received
Current behaviour:
	No upstream gets created
Changed behaviour:
	Upstream data structure created with below info
	upstream_addr: INADDR_ANY
	channel_oil iif:  MAXVIF
	channel_oil is_valid: FALSE (flag introduced to indicate if this entry is valid to get installed in hardware)
	RPF details: Not valid
	Join state: NOT_JOINED
	Kernal installed: FALSE

Scenario 2: Dummy upstream exists
Event: RP configured
Current Behaviour:
	upstream address updated for the dummy upstream created.
Changed Behaviour:
	upstream_addr: RP address
	channel_oil iif:  MAXVIF
	channel_oil is_valid: FALSE
	RPF details: only RP address updated
	Join state: NOT_JOINED
	Kernel installed: FALSE

Scenario 3: Dummy upstream exists
Event: RP becomes reachable
Current Behaviour:
	Update channel oil, rpf details in the upstream and install in hardware
Changed Behaviour:
	upstream_addr: RP Adress
	channel_oil iif:  MAXVIF
	channel_oil is_valid: FALSE
	RPF details: RPF details updated via NHT callback
	Join state: JOINED
	Kernel installed: TRUE

Scenario 4: MRoute exists
Event: RP gets deleted
Current behaviour:
	Nothing got updated in him upstream and channel oil,
	join timer still runs. Mroute still exists in kernel.
Changed behaviour:
	upstream_addr: INADDR_ANY
	channel_oil iif:  MAXVIF
	channel_oil is_valid: FALSE
	RPF details: Not valid
	Join state: NOT_JOINED (also sent prune towards deleted RPF nbr)
	Kernel installed: FALSE

Scenario 5: MRoute Exists
Event: RP unreachable
Current behaviour:
	Nothing got updated in him upstream and channel oil,
	join timer still runs. Mroute sdeleted from  kernel.
Changed behaviour:
	upstream_addr: RP address
	channel_oil iif:  MAXVIF
	channel_oil is_valid: FALSE
	RPF details: only RP address updated
	Join state: NOT_JOINED (also sent prune towards deleted RPF nbr)
	Kernel installed: FALSE

Scenario 6: Mroute exists
Event: Better RP configured with precise group range & reachable.
Current behaviour:
	No effect on existing route.
Changed behaviour:
	Upstream address: Better RP
	RPF interface: towards the better RP
	Join state: JOINED (Send a prune towards the old RP and send a join
		towards the better RP)

Scenario 7: Mroute exists
Event: RP deleted and another RP with broad group range fits this group & reachable
Current behaviour:
	No effect on current behaviour
Changed behaviour:
	Upstream address: next available RP
	RPF interface: towards the next available RP
	Join state: JOINED (Send a prune towards the old RP and send a join
		towards the better RP)
Signed-off-by: Sarita Patra <saritap@vmware.com>

2 files changed, 42 insertions, 2 deletions

diff --git a/pimd/pim_oil.h b/pimd/pim_oil.h
index 94d3840e98..fef414cc85 100644
--- a/pimd/pim_oil.h
+++ b/pimd/pim_oil.h
@@ -64,12 +64,32 @@ struct channel_counts {
 
   Each channel_oil.oil is used to control an (S,G) entry in the Kernel
   Multicast Forwarding Cache.
+
+  There is a case when we create a channel_oil but don't install in the kernel
+
+  Case where (S, G) entry not installed in the kernel:
+    FRR receives IGMP/PIM (*, G) join and RP is not configured or
+    not-reachable, then create a channel_oil for the group G with the incoming
+    interface(channel_oil.oil.mfcc_parent) as invalid i.e "MAXVIF" and populate
+    the outgoing interface where join is received. Keep this entry in the stack,
+    but don't install in the kernel(channel_oil.installed = 0).
+
+  Case where (S, G) entry installed in the kernel:
+    When RP is configured and is reachable for the group G, and receiving a
+    join if channel_oil is already present then populate the incoming interface
+    and install the entry in the kernel, if channel_oil not present, then create
+    a new_channel oil(channel_oil.installed = 1).
+
+  is_valid: indicate if this entry is valid to get installed in kernel.
+  installed: indicate if this entry is installed in the kernel.
+
 */
 
 struct channel_oil {
 	struct pim_instance *pim;
 
 	struct mfcctl oil;
+	bool is_valid;
 	int installed;
 	int oil_inherited_rescan;
 	int oil_size;
diff --git a/pimd/pim_upstream.h b/pimd/pim_upstream.h
index f44b95c811..70e70140d1 100644
--- a/pimd/pim_upstream.h
+++ b/pimd/pim_upstream.h
@@ -88,10 +88,30 @@ enum pim_upstream_sptbit {
 
 /*
   Upstream (S,G) channel in Joined state
-
   (S,G) in the "Not Joined" state is not represented
-
   See RFC 4601: 4.5.7.  Sending (S,G) Join/Prune Message
+
+  upstream_addr : Who we are talking to.
+  For (*, G), upstream_addr is RP address or INADDR_ANY(if RP not configured)
+  For (S, G), upstream_addr is source address
+
+  rpf: contains the nexthop information to whom we are talking to.
+
+  join_state: JOINED/NOTJOINED
+
+  In the case when FRR receives IGMP/PIM (*, G) join for group G and RP is not
+  configured, then create a pim_upstream with the below information.
+  pim_upstream->upstream address: INADDR_ANY
+  pim_upstream->rpf: Unknown
+  pim_upstream->state: NOTJOINED
+
+  When a new RP gets configured for G, find the corresponding pim upstream (*,G)
+  entries and update the upstream address as new RP address if it the better one
+  for the group G.
+
+  When RP becomes reachable, populate the nexthop information in
+  pim_upstream->rpf and update the state to JOINED.
+
 */
 struct pim_upstream {
 	struct pim_upstream *parent;