Add some doxygen tags

Also add an index of node names

Change-Id: Id65c2e607976d8bad73deb738035a471be077196
Signed-off-by: Dave Barach <dave@barachs.net>
Signed-off-by: Chris Luke <chrisy@flirble.org>

4 files changed, 176 insertions, 1 deletions

diff --git a/doxygen/doxygen.cfg b/doxygen/doxygen.cfg
index ec4312c9fe7..cc10a9d46fb 100644
--- a/doxygen/doxygen.cfg
+++ b/doxygen/doxygen.cfg
@@ -229,6 +229,7 @@ TAB_SIZE               = 8
 # newlines.
 
 ALIASES                =
+ALIASES += "node=@xrefitem nodes \"Node Identifier\" \"Node Identifiers\" @c "
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
diff --git a/vlib/vlib/buffer_node.h b/vlib/vlib/buffer_node.h
index 0fa5c8093ca..5985ccf500d 100644
--- a/vlib/vlib/buffer_node.h
+++ b/vlib/vlib/buffer_node.h
@@ -40,6 +40,33 @@
 #ifndef included_vlib_buffer_node_h
 #define included_vlib_buffer_node_h
 
+/** \file 
+    vlib buffer/node functions
+*/
+
+/** \brief Finish enqueueing two buffers forward in the graph.
+ Standard dual loop boilerplate element. This is a MACRO,
+ with MULTIPLE SIDE EFFECTS. In the ideal case, 
+ <code>next_index == next0 == next1</code>,
+ which means that the speculative enqueue at the top of the dual loop
+ has correctly dealt with both packets. In that case, the macro does
+ nothing at all.
+
+ @param vm vlib_main_t pointer, varies by thread
+ @param node current node vlib_node_runtime_t pointer
+ @param next_index speculated next index used for both packets
+ @param to_next speculated vector pointer used for both packets
+ @param n_left_to_next number of slots left in speculated vector
+ @param bi0 first buffer index
+ @param bi1 second buffer index
+ @param next0 actual next index to be used for the first packet
+ @param next1 actual next index to be used for the second packet
+
+ @return @c next_index -- speculative next index to be used for future packets
+ @return @c to_next -- speculative frame to be used for future packets
+ @return @c n_left_to_next -- number of slots left in speculative frame
+*/
+
 #define vlib_validate_buffer_enqueue_x2(vm,node,next_index,to_next,n_left_to_next,bi0,bi1,next0,next1) \
 do {									\
   int enqueue_code = (next0 != next_index) + 2*(next1 != next_index);	\
@@ -80,6 +107,26 @@ do {									\
     }									\
 } while (0)
 
+/** \brief Finish enqueueing one buffer forward in the graph.
+ Standard single loop boilerplate element. This is a MACRO,
+ with MULTIPLE SIDE EFFECTS. In the ideal case,
+ <code>next_index == next0</code>,
+ which means that the speculative enqueue at the top of the single loop
+ has correctly dealt with the packet in hand. In that case, the macro does
+ nothing at all.
+
+ @param vm vlib_main_t pointer, varies by thread
+ @param node current node vlib_node_runtime_t pointer
+ @param next_index speculated next index used for both packets
+ @param to_next speculated vector pointer used for both packets
+ @param n_left_to_next number of slots left in speculated vector
+ @param bi0 first buffer index
+ @param next0 actual next index to be used for the first packet
+
+ @return @c next_index -- speculative next index to be used for future packets
+ @return @c to_next -- speculative frame to be used for future packets
+ @return @c n_left_to_next -- number of slots left in speculative frame
+*/
 #define vlib_validate_buffer_enqueue_x1(vm,node,next_index,to_next,n_left_to_next,bi0,next0) \
 do {									\
   if (PREDICT_FALSE (next0 != next_index))				\
diff --git a/vlib/vlib/node_funcs.h b/vlib/vlib/node_funcs.h
index 18342e2661d..f567ce54909 100644
--- a/vlib/vlib/node_funcs.h
+++ b/vlib/vlib/node_funcs.h
@@ -37,15 +37,34 @@
  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/** \file 
+    vlib node functions
+*/
+
+
 #ifndef included_vlib_node_funcs_h
 #define included_vlib_node_funcs_h
 
 #include <vppinfra/fifo.h>
 
+/** \brief Get vlib node by index.
+ @warning This function will ASSERT if @c i is out of range.
+ @param vm vlib_main_t pointer, varies by thread
+ @param i node index.
+ @return pointer to the requested vlib_node_t.
+*/
+
 always_inline vlib_node_t *
 vlib_get_node (vlib_main_t * vm, u32 i)
 { return vec_elt (vm->node_main.nodes, i); }
 
+/** \brief Get vlib node by graph arc (next) index.
+ @param vm vlib_main_t pointer, varies by thread
+ @param node_index index of original node
+ @param next_index graph arc index
+ @return pointer to the vlib_node_t at the end of the indicated arc
+*/
+
 always_inline vlib_node_t *
 vlib_get_next_node (vlib_main_t * vm, u32 node_index, u32 next_index)
 {
@@ -57,6 +76,12 @@ vlib_get_next_node (vlib_main_t * vm, u32 node_index, u32 next_index)
   return vlib_get_node (vm, n->next_nodes[next_index]);
 }
 
+/** \brief Get node runtime by node index.
+ @param vm vlib_main_t pointer, varies by thread
+ @param node_index index of node
+ @return pointer to the indicated vlib_node_runtime_t
+*/
+
 always_inline vlib_node_runtime_t *
 vlib_node_get_runtime (vlib_main_t * vm, u32 node_index)
 {
@@ -72,6 +97,12 @@ vlib_node_get_runtime (vlib_main_t * vm, u32 node_index)
     }
 }
 
+/** \brief Get node runtime private data by node index.
+ @param vm vlib_main_t pointer, varies by thread
+ @param node_index index of the node
+ @return pointer to the indicated vlib_node_runtime_t private data
+*/
+
 always_inline void *
 vlib_node_get_runtime_data (vlib_main_t * vm, u32 node_index)
 {
@@ -79,6 +110,13 @@ vlib_node_get_runtime_data (vlib_main_t * vm, u32 node_index)
   return r->runtime_data;
 }
 
+/** \brief Set node runtime private data.
+ @param vm vlib_main_t pointer, varies by thread
+ @param node_index index of the node
+ @param runtime_data arbitrary runtime private data
+ @param n_runtime_data_bytes size of runtime private data
+*/
+
 always_inline void
 vlib_node_set_runtime_data (vlib_main_t * vm, u32 node_index,
 			    void * runtime_data,
@@ -96,6 +134,11 @@ vlib_node_set_runtime_data (vlib_main_t * vm, u32 node_index,
     clib_memcpy (r->runtime_data, n->runtime_data, vec_len (n->runtime_data));
 }
 
+/** \brief Set node dispatch state.
+ @param vm vlib_main_t pointer, varies by thread
+ @param node_index index of the node
+ @param new_state new state for node, see vlib_node_state_t
+*/
 always_inline void
 vlib_node_set_state (vlib_main_t * vm, u32 node_index, vlib_node_state_t new_state)
 {
@@ -198,13 +241,27 @@ vlib_frame_vector_byte_offset (u32 scalar_size)
 		     VLIB_FRAME_VECTOR_ALIGN);
 }
 
+/** \brief Get pointer to frame vector data.
+ @param f vlib_frame_t pointer
+ @return pointer to first vector element in frame
+*/
 always_inline void *
 vlib_frame_vector_args (vlib_frame_t * f)
 {
   return (void *) f + vlib_frame_vector_byte_offset (f->scalar_size);
 }
 
-/* Scalar data lies before aligned vector data. */
+/** \brief Get pointer to frame scalar data.
+
+ @warning This is almost certainly not the function you wish to call.
+ See @ref vlib_frame_vector_args instead.
+
+ @param f vlib_frame_t pointer
+
+ @return arbitrary node scalar data
+
+ @sa vlib_frame_vector_args
+*/
 always_inline void *
 vlib_frame_args (vlib_frame_t * f)
 { return vlib_frame_vector_args (f) - f->scalar_size; }
@@ -232,6 +289,20 @@ vlib_node_runtime_get_next_frame (vlib_main_t * vm,
   return nf;
 }
 
+/** \brief Get pointer to frame by (@c node_index, @c next_index).
+
+ @warning This is not a function that you should call directly.
+ See @ref vlib_get_next_frame instead.
+
+ @param vm vlib_main_t pointer, varies by thread
+ @param node_index index of the node
+ @param next_index graph arc index
+
+ @return pointer to the requested vlib_next_frame_t
+
+ @sa vlib_get_next_frame
+*/
+
 always_inline vlib_next_frame_t *
 vlib_node_get_next_frame (vlib_main_t * vm,
 			  u32 node_index,
@@ -262,6 +333,19 @@ do {									\
   (n_vectors_left) = VLIB_FRAME_SIZE - _n;				\
 } while (0)
 
+
+/** \brief Get pointer to next frame vector data by 
+    (@c vlib_node_runtime_t, @c next_index).
+ Standard single/dual loop boilerplate element.
+ @attention This is a MACRO, with SIDE EFFECTS.
+
+ @param vm vlib_main_t pointer, varies by thread
+ @param node current node vlib_node_runtime_t pointer
+ @param next_index requested graph arc index
+
+ @return @c vectors -- pointer to next available vector slot
+ @return @c n_vectors_left -- number of vector slots available
+*/
 #define vlib_get_next_frame(vm,node,next_index,vectors,n_vectors_left)	\
   vlib_get_next_frame_macro (vm, node, next_index,			\
 			     vectors, n_vectors_left,			\
@@ -272,6 +356,13 @@ do {									\
 			     vectors, n_vectors_left,			\
 			     /* alloc new frame */ 1)
 
+/** \brief Release pointer to next frame vector data.
+ Standard single/dual loop boilerplate element.
+ @param vm vlib_main_t pointer, varies by thread
+ @param r current node vlib_node_runtime_t pointer
+ @param next_index graph arc index
+ @param n_packets_left number of slots still available in vector
+*/
 void
 vlib_put_next_frame (vlib_main_t * vm,
 		     vlib_node_runtime_t * r,
diff --git a/vnet/vnet/ip/ip4_forward.c b/vnet/vnet/ip/ip4_forward.c
index 939835ae66a..45699b128fe 100644
--- a/vnet/vnet/ip/ip4_forward.c
+++ b/vnet/vnet/ip/ip4_forward.c
@@ -45,6 +45,10 @@
 #include <vnet/srp/srp.h>	/* for srp_hw_interface_class */
 #include <vnet/api_errno.h>     /* for API error numbers */
 
+/** \file
+    vnet ip4 forwarding 
+*/
+
 /* This is really, really simple but stupid fib. */
 u32
 ip4_fib_lookup_with_table (ip4_main_t * im, u32 fib_index,
@@ -1002,6 +1006,38 @@ ip4_lookup_inline (vlib_main_t * vm,
   return frame->n_vectors;
 }
 
+/** \brief IPv4 lookup node.
+    @node ip4-lookup
+
+    This is the main IPv4 lookup dispatch node.
+
+    @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)->sw_if_index[VLIB_RX]</code>
+        - Indicates the @c sw_if_index value of the interface that the
+	  packet was received on.
+    - <code>vnet_buffer(b)->sw_if_index[VLIB_TX]</code>
+        - When the value is @c ~0 then the node performs a longest prefix
+          match (LPM) for the packet destination address in the FIB attached
+          to the receive interface.
+        - Otherwise perform LPM for the packet destination address in the
+          indicated FIB. In this case <code>[VLIB_TX]</code> is a FIB index
+          value (0, 1, ...) and not a VRF id.
+
+    @em Sets:
+    - <code>vnet_buffer(b)->ip.adj_index[VLIB_TX]</code>
+        - The lookup result adjacency index.
+
+    <em>Next Index:</em>
+    - Dispatches the packet to the node index found in
+      ip_adjacency_t @c adj->lookup_next_index
+      (where @c adj is the lookup result adjacency).
+*/
 static uword
 ip4_lookup (vlib_main_t * vm,
 	    vlib_node_runtime_t * node,