Document more nodes

Change-Id: Ib8ef0559aa0573bf1229e9c794d48520197f9c8a
Signed-off-by: Dave Barach <dave@barachs.net>

3 files changed, 142 insertions, 0 deletions

diff --git a/vnet/vnet/devices/dpdk/node.c b/vnet/vnet/devices/dpdk/node.c
index 689e4f8709f..942274b0bf5 100644
--- a/vnet/vnet/devices/dpdk/node.c
+++ b/vnet/vnet/devices/dpdk/node.c
@@ -558,6 +558,48 @@ static inline void poll_rate_limit(dpdk_main_t * dm)
   }
 }
 
+/** \brief Main DPDK input node
+    @node dpdk-input
+
+    This is the main DPDK input node: across each assigned interface,
+    call rte_eth_rx_burst(...) or similar to obtain a vector of
+    packets to process. Handle early packet discard. Derive @c
+    vlib_buffer_t metadata from <code>struct rte_mbuf</code> metadata,
+    Depending on the resulting metadata: adjust <code>b->current_data,
+    b->current_length </code> and dispatch directly to
+    ip4-input-no-checksum, or ip6-input. Trace the packet if required.
+
+    @param vm vlib_main_t corresponding to the current thread
+    @param node vlib_node_runtime_t
+    @param frame vlib_frame_t input-node, not used.
+
+    @par Graph mechanics: buffer metadata, next index usage
+
+    @em Uses:
+    - <code>struct rte_mbuf mb->ol_flags</code>
+        - PKT_EXT_RX_PKT_ERROR, PKT_EXT_RX_BAD_FCS
+        PKT_RX_IP_CKSUM_BAD, PKT_RX_L4_CKSUM_BAD
+    - <code> RTE_ETH_IS_xxx_HDR(mb->packet_type) </code>
+        - packet classification result
+
+    @em Sets:
+    - <code>b->error</code> if the packet is to be dropped immediately
+    - <code>b->current_data, b->current_length</code>
+        - adjusted as needed to skip the L2 header in  direct-dispatch cases
+    - <code>vnet_buffer(b)->sw_if_index[VLIB_RX]</code>
+        - rx interface sw_if_index
+    - <code>vnet_buffer(b)->sw_if_index[VLIB_TX] = ~0</code>
+        - required by ipX-lookup
+    - <code>b->flags</code>
+        - to indicate multi-segment pkts (VLIB_BUFFER_NEXT_PRESENT), etc.
+
+    <em>Next Nodes:</em>
+    - Static arcs to: error-drop, ethernet-input,
+      ip4-input-no-checksum, ip6-input, mpls-gre-input 
+    - per-interface redirection, controlled by
+      <code>xd->per_interface_next_index</code>
+*/
+
 static uword
 dpdk_input (vlib_main_t * vm,
 	    vlib_node_runtime_t * node,
diff --git a/vnet/vnet/ip/ip4_forward.c b/vnet/vnet/ip/ip4_forward.c
index 45699b128fe..35c42d822b7 100644
--- a/vnet/vnet/ip/ip4_forward.c
+++ b/vnet/vnet/ip/ip4_forward.c
@@ -2919,6 +2919,38 @@ ip4_rewrite_inline (vlib_main_t * vm,
   return frame->n_vectors;
 }
 
+
+/** \brief IPv4 transit rewrite node.
+    @node ip4-rewrite-transit
+
+    This is the IPv4 transit-rewrite node: decrement TTL, fix the ipv4
+    header checksum, fetch the ip adjacency, check the outbound mtu,
+    apply the adjacency rewrite, and send pkts to the adjacency
+    rewrite header's rewrite_next_index.
+
+    @param vm vlib_main_t corresponding to the current thread
+    @param node vlib_node_runtime_t
+    @param frame vlib_frame_t whose contents should be dispatched
+
+    @par Graph mechanics: buffer metadata, next index usage
+
+    @em Uses:
+    - <code>vnet_buffer(b)->ip.adj_index[VLIB_TX]</code>
+        - the rewrite adjacency index
+    - <code>adj->lookup_next_index</code>
+        - Must be IP_LOOKUP_NEXT_REWRITE or IP_LOOKUP_NEXT_ARP, otherwise
+          the packet will be dropped. 
+    - <code>adj->rewrite_header</code>
+        - Rewrite string length, rewrite string, next_index
+
+    @em Sets:
+    - <code>b->current_data, b->current_length</code>
+        - Updated net of applying the rewrite string
+
+    <em>Next Indices:</em>
+    - <code> adj->rewrite_header.next_index </code>
+      or @c error-drop 
+*/
 static uword
 ip4_rewrite_transit (vlib_main_t * vm,
 		     vlib_node_runtime_t * node,
@@ -2928,6 +2960,39 @@ ip4_rewrite_transit (vlib_main_t * vm,
 			     /* rewrite_for_locally_received_packets */ 0);
 }
 
+/** \brief IPv4 local rewrite node.
+    @node ip4-rewrite-local
+
+    This is the IPv4 local rewrite node. Fetch the ip adjacency, check
+    the outbound interface mtu, apply the adjacency rewrite, and send
+    pkts to the adjacency rewrite header's rewrite_next_index. Deal
+    with hemorrhoids of the form "some clown sends an icmp4 w/ src =
+    dst = interface addr."
+
+    @param vm vlib_main_t corresponding to the current thread
+    @param node vlib_node_runtime_t
+    @param frame vlib_frame_t whose contents should be dispatched
+
+    @par Graph mechanics: buffer metadata, next index usage
+
+    @em Uses:
+    - <code>vnet_buffer(b)->ip.adj_index[VLIB_RX]</code>
+        - the rewrite adjacency index
+    - <code>adj->lookup_next_index</code>
+        - Must be IP_LOOKUP_NEXT_REWRITE or IP_LOOKUP_NEXT_ARP, otherwise
+          the packet will be dropped. 
+    - <code>adj->rewrite_header</code>
+        - Rewrite string length, rewrite string, next_index
+
+    @em Sets:
+    - <code>b->current_data, b->current_length</code>
+        - Updated net of applying the rewrite string
+
+    <em>Next Indices:</em>
+    - <code> adj->rewrite_header.next_index </code>
+      or @c error-drop 
+*/
+
 static uword
 ip4_rewrite_local (vlib_main_t * vm,
 		   vlib_node_runtime_t * node,
diff --git a/vnet/vnet/ip/ip4_input.c b/vnet/vnet/ip/ip4_input.c
index c5281c4eb1d..1c7d327dc18 100644
--- a/vnet/vnet/ip/ip4_input.c
+++ b/vnet/vnet/ip/ip4_input.c
@@ -328,6 +328,41 @@ ip4_input_inline (vlib_main_t * vm,
   return frame->n_vectors;
 }
 
+/** \brief IPv4 input node.
+    @node ip4-input
+
+    This is the IPv4 input node: validates ip4 header checksums,
+    verifies ip header lengths, discards pkts with expired TTLs,
+    and sends pkts to the set of ip feature nodes configured on
+    the rx interface.
+
+    @param vm vlib_main_t corresponding to the current thread
+    @param node vlib_node_runtime_t
+    @param frame vlib_frame_t whose contents should be dispatched
+
+    @par Graph mechanics: buffer metadata, next index usage
+
+    @em Uses:
+    - ip_config_main_t cm corresponding to each pkt's dst address unicast / 
+      multicast status.
+    - <code>b->current_config_index</code> corresponding to each pkt's
+      rx sw_if_index. 
+         - This sets the per-packet graph trajectory, ensuring that
+           each packet visits the per-interface features in order.
+
+    - <code>vnet_buffer(b)->sw_if_index[VLIB_RX]</code>
+        - Indicates the @c sw_if_index value of the interface that the
+	  packet was received on.
+
+    @em Sets:
+    - <code>vnet_buffer(b)->ip.adj_index[VLIB_TX]</code>
+        - The lookup result adjacency index.
+
+    <em>Next Indices:</em>
+    - Dispatches pkts to the (first) feature node:
+      <code> vnet_get_config_data (... &next0 ...); </code>
+      or @c error-drop 
+*/
 static uword
 ip4_input (vlib_main_t * vm,
 	   vlib_node_runtime_t * node,