VPP-303 - Documentation changes for vnet/vnet/sr

Change-Id: If8b76959d7c29c216bf03609483a2c9e1d034f46
Signed-off-by: Keith Burns (alagalah) <alagalah@gmail.com>

4 files changed, 390 insertions, 60 deletions

diff --git a/vnet/vnet/sr/sr.c b/vnet/vnet/sr/sr.c
index 0ae462ac7d3..9c2d591102d 100644
--- a/vnet/vnet/sr/sr.c
+++ b/vnet/vnet/sr/sr.c
@@ -15,6 +15,11 @@
  * limitations under the License.
  */
 
+/**
+ * @file
+ * @brief Segment Routing main functions
+ *
+ */
 #include <vnet/vnet.h>
 #include <vnet/sr/sr.h>
 
@@ -23,6 +28,13 @@
 ip6_sr_main_t sr_main;
 static vlib_node_registration_t sr_local_node;
 
+/**
+ * @brief Use passed HMAC key in ip6_sr_header_t in OpenSSL HMAC routines
+ *
+ * @param sm ip6_sr_main_t *
+ * @param ip ip6_header_t *
+ * @param sr ip6_sr_header_t *
+ */
 void
 sr_fix_hmac (ip6_sr_main_t * sm, ip6_header_t * ip, ip6_sr_header_t * sr)
 {
@@ -92,6 +104,14 @@ sr_fix_hmac (ip6_sr_main_t * sm, ip6_header_t * ip, ip6_sr_header_t * sr)
   HMAC_CTX_cleanup (sm->hmac_ctx);
 }
 
+/**
+ * @brief Format function for decoding various SR flags
+ *
+ * @param s u8 * - formatted string
+ * @param args va_list * - u16 flags
+ *
+ * @return formatted output string u8 *
+ */
 u8 *
 format_ip6_sr_header_flags (u8 * s, va_list * args)
 {
@@ -135,6 +155,14 @@ format_ip6_sr_header_flags (u8 * s, va_list * args)
   return s;
 }
 
+/**
+ * @brief Format function for decoding ip6_sr_header_t
+ *
+ * @param s u8 * - formatted string
+ * @param args va_list * - ip6_sr_header_t
+ *
+ * @return formatted output string u8 *
+ */
 u8 *
 format_ip6_sr_header (u8 * s, va_list * args)
 {
@@ -195,6 +223,14 @@ format_ip6_sr_header (u8 * s, va_list * args)
   return s;
 }
 
+/**
+ * @brief Format function for decoding ip6_sr_header_t with length
+ *
+ * @param s u8 * - formatted string
+ * @param args va_list * - ip6_header_t + ip6_sr_header_t
+ *
+ * @return formatted output string u8 *
+ */
 u8 *
 format_ip6_sr_header_with_length (u8 * s, va_list * args)
 {
@@ -213,7 +249,11 @@ format_ip6_sr_header_with_length (u8 * s, va_list * args)
   return s;
 }
 
-#if DPDK > 0			/* Cannot call replicate yet without DPDK */
+/**
+ * @brief Defined valid next nodes
+ * @note Cannot call replicate yet without DPDK
+*/
+#if DPDK > 0
 #define foreach_sr_rewrite_next                 \
 _(ERROR, "error-drop")                          \
 _(IP6_LOOKUP, "ip6-lookup")                     \
@@ -226,6 +266,9 @@ _(IP6_LOOKUP, "ip6-lookup")                     \
 _(SR_LOCAL, "sr-local")
 #endif /* DPDK */
 
+/**
+ * @brief Struct for defined valid next nodes
+*/
 typedef enum
 {
 #define _(s,n) SR_REWRITE_NEXT_##s,
@@ -234,6 +277,9 @@ typedef enum
     SR_REWRITE_N_NEXT,
 } sr_rewrite_next_t;
 
+/**
+ * @brief Struct for data for SR rewrite packet trace
+ */
 typedef struct
 {
   ip6_address_t src, dst;
@@ -243,12 +289,18 @@ typedef struct
   u8 sr[256];
 } sr_rewrite_trace_t;
 
+/**
+ * @brief Error strings for SR rewrite
+ */
 static char *sr_rewrite_error_strings[] = {
 #define sr_error(n,s) s,
 #include "sr_error.def"
 #undef sr_error
 };
 
+/**
+ * @brief Struct for SR rewrite error strings
+ */
 typedef enum
 {
 #define sr_error(n,s) SR_REWRITE_ERROR_##n,
@@ -258,6 +310,9 @@ typedef enum
 } sr_rewrite_error_t;
 
 
+/**
+ * @brief Format function for SR rewrite trace.
+ */
 u8 *
 format_sr_rewrite_trace (u8 * s, va_list * args)
 {
@@ -287,6 +342,16 @@ format_sr_rewrite_trace (u8 * s, va_list * args)
   return s;
 }
 
+/**
+ * @brief Main processing dual-loop for Segment Routing Rewrite
+ * @node sr-rewrite
+ *
+ * @param vm vlib_main_t *
+ * @param node vlib_node_runtime_t *
+ * @param from_frame vlib_frame_t *
+ *
+ * @return from_frame->n_vectors uword
+ */
 static uword
 sr_rewrite (vlib_main_t * vm,
 	    vlib_node_runtime_t * node, vlib_frame_t * from_frame)
@@ -703,6 +768,15 @@ VLIB_NODE_FUNCTION_MULTIARCH (sr_rewrite_node, sr_rewrite)
   return 0;
 }
 
+/**
+ * @brief Find or add if not found - HMAC shared secret
+ *
+ * @param sm ip6_sr_main_t *
+ * @param secret u8 *
+ * @param indexp u32 *
+ *
+ * @return ip6_sr_hmac_key_t *
+ */
 static ip6_sr_hmac_key_t *
 find_or_add_shared_secret (ip6_sr_main_t * sm, u8 * secret, u32 * indexp)
 {
@@ -752,7 +826,13 @@ find_or_add_shared_secret (ip6_sr_main_t * sm, u8 * secret, u32 * indexp)
   return (key);
 }
 
-
+/**
+ * @brief Add or Delete a Segment Routing tunnel.
+ *
+ * @param a ip6_sr_add_del_tunnel_args_t *
+ *
+ * @return retval int
+ */
 int
 ip6_sr_add_del_tunnel (ip6_sr_add_del_tunnel_args_t * a)
 {
@@ -1045,6 +1125,15 @@ ip6_sr_add_del_tunnel (ip6_sr_add_del_tunnel_args_t * a)
   return 0;
 }
 
+/**
+ * @brief CLI parser for Add or Delete a Segment Routing tunnel.
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 sr_add_del_tunnel_command_fn (vlib_main_t * vm,
 			      unformat_input_t * input,
@@ -1216,6 +1305,13 @@ VLIB_CLI_COMMAND (sr_tunnel_command, static) = {
 };
 /* *INDENT-ON* */
 
+/**
+ * @brief Display Segment Routing tunnel
+ *
+ * @param vm vlib_main_t *
+ * @param t ip6_sr_tunnel_t *
+ *
+ */
 void
 ip6_sr_tunnel_display (vlib_main_t * vm, ip6_sr_tunnel_t * t)
 {
@@ -1252,6 +1348,15 @@ ip6_sr_tunnel_display (vlib_main_t * vm, ip6_sr_tunnel_t * t)
   return;
 }
 
+/**
+ * @brief CLI Parser for Display Segment Routing tunnel
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 show_sr_tunnel_fn (vlib_main_t * vm,
 		   unformat_input_t * input, vlib_cli_command_t * cmd)
@@ -1310,6 +1415,13 @@ VLIB_CLI_COMMAND (show_sr_tunnel_command, static) = {
 };
 /* *INDENT-ON* */
 
+/**
+ * @brief Add or Delete a Segment Routing policy
+ *
+ * @param a ip6_sr_add_del_policy_args_t *
+ *
+ * @return retval int
+ */
 int
 ip6_sr_add_del_policy (ip6_sr_add_del_policy_args_t * a)
 {
@@ -1383,7 +1495,15 @@ ip6_sr_add_del_policy (ip6_sr_add_del_policy_args_t * a)
   return 0;
 }
 
-
+/**
+ * @brief CLI Parser for Add or Delete a Segment Routing policy
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 sr_add_del_policy_command_fn (vlib_main_t * vm,
 			      unformat_input_t * input,
@@ -1466,6 +1586,15 @@ VLIB_CLI_COMMAND (sr_policy_command, static) = {
 };
 /* *INDENT-ON* */
 
+/**
+ * @brief CLI Parser for Displaying Segment Routing policy
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 show_sr_policy_fn (vlib_main_t * vm,
 		   unformat_input_t * input, vlib_cli_command_t * cmd)
@@ -1537,6 +1666,14 @@ VLIB_CLI_COMMAND (show_sr_policy_command, static) = {
 };
 /* *INDENT-ON* */
 
+/**
+ * @brief Add or Delete a mapping of IP6 multicast address
+ * to Segment Routing policy.
+ *
+ * @param a ip6_sr_add_del_multicastmap_args_t *
+ *
+ * @return retval int
+ */
 int
 ip6_sr_add_del_multicastmap (ip6_sr_add_del_multicastmap_args_t * a)
 {
@@ -1634,6 +1771,16 @@ ip6_sr_add_del_multicastmap (ip6_sr_add_del_multicastmap_args_t * a)
   return 0;
 }
 
+/**
+ * @brief CLI Parser for Adding or Delete a mapping of IP6 multicast address
+ * to Segment Routing policy.
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 sr_add_del_multicast_map_command_fn (vlib_main_t * vm,
 				     unformat_input_t * input,
@@ -1716,6 +1863,16 @@ VLIB_CLI_COMMAND (sr_multicast_map_command, static) = {
 };
 /* *INDENT-ON* */
 
+/**
+ * @brief CLI Parser for Displaying a mapping of IP6 multicast address
+ * to Segment Routing policy.
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 show_sr_multicast_map_fn (vlib_main_t * vm,
 			  unformat_input_t * input, vlib_cli_command_t * cmd)
@@ -1768,6 +1925,9 @@ VLIB_CLI_COMMAND (show_sr_multicast_map_command, static) = {
 #define foreach_sr_fix_dst_addr_next            \
 _(DROP, "error-drop")
 
+/**
+ * @brief Struct for valid next-nodes for SR fix destination address node
+ */
 typedef enum
 {
 #define _(s,n) SR_FIX_DST_ADDR_NEXT_##s,
@@ -1776,12 +1936,18 @@ typedef enum
     SR_FIX_DST_ADDR_N_NEXT,
 } sr_fix_dst_addr_next_t;
 
+/**
+ * @brief Error strings for SR Fix Destination rewrite
+ */
 static char *sr_fix_dst_error_strings[] = {
 #define sr_fix_dst_error(n,s) s,
 #include "sr_fix_dst_error.def"
 #undef sr_fix_dst_error
 };
 
+/**
+ * @brief Struct for errors for SR Fix Destination rewrite
+ */
 typedef enum
 {
 #define sr_fix_dst_error(n,s) SR_FIX_DST_ERROR_##n,
@@ -1790,6 +1956,9 @@ typedef enum
   SR_FIX_DST_N_ERROR,
 } sr_fix_dst_error_t;
 
+/**
+ * @brief Information for fix address trace
+ */
 typedef struct
 {
   ip6_address_t src, dst;
@@ -1798,6 +1967,9 @@ typedef struct
   u8 sr[256];
 } sr_fix_addr_trace_t;
 
+/**
+ * @brief Formatter for fix address trace
+ */
 u8 *
 format_sr_fix_addr_trace (u8 * s, va_list * args)
 {
@@ -1831,6 +2003,16 @@ format_sr_fix_addr_trace (u8 * s, va_list * args)
   return s;
 }
 
+/**
+ * @brief Fix SR destination address - dual-loop
+ *
+ * @node sr-fix-dst-addr
+ * @param vm vlib_main_t *
+ * @param node vlib_node_runtime_t *
+ * @param from_frame vlib_frame_t *
+ *
+ * @return from_frame->n_vectors uword
+ */
 static uword
 sr_fix_dst_addr (vlib_main_t * vm,
 		 vlib_node_runtime_t * node, vlib_frame_t * from_frame)
@@ -2067,10 +2249,16 @@ VLIB_NODE_FUNCTION_MULTIARCH (sr_fix_dst_addr_node, sr_fix_dst_addr)
 
 VLIB_INIT_FUNCTION (sr_init);
 
+/**
+ * @brief Definition of next-nodes for SR local
+ */
 #define foreach_sr_local_next                   \
   _ (ERROR, "error-drop")                       \
   _ (IP6_LOOKUP, "ip6-lookup")
 
+/**
+ * @brief Struct for definition of next-nodes for SR local
+ */
 typedef enum
 {
 #define _(s,n) SR_LOCAL_NEXT_##s,
@@ -2079,6 +2267,9 @@ typedef enum
     SR_LOCAL_N_NEXT,
 } sr_local_next_t;
 
+/**
+ * @brief Struct for packet trace of SR local
+ */
 typedef struct
 {
   u8 next_index;
@@ -2088,12 +2279,18 @@ typedef struct
   u8 sr[256];
 } sr_local_trace_t;
 
+/**
+ * @brief Definition of SR local error-strings
+ */
 static char *sr_local_error_strings[] = {
 #define sr_error(n,s) s,
 #include "sr_error.def"
 #undef sr_error
 };
 
+/**
+ * @brief Struct for definition of SR local error-strings
+ */
 typedef enum
 {
 #define sr_error(n,s) SR_LOCAL_ERROR_##n,
@@ -2102,6 +2299,14 @@ typedef enum
   SR_LOCAL_N_ERROR,
 } sr_local_error_t;
 
+/**
+ * @brief Format SR local trace
+ *
+ * @param s u8 *
+ * @param args va_list *
+ *
+ * @return s u8 *
+ */
 u8 *
 format_sr_local_trace (u8 * s, va_list * args)
 {
@@ -2123,7 +2328,15 @@ format_sr_local_trace (u8 * s, va_list * args)
 
 
 /* $$$$ fixme: smp, don't copy data, cache input, output (maybe) */
-
+/**
+ * @brief Validate the SR HMAC
+ *
+ * @param sm ip6_sr_main_t *
+ * @param ip ip6_header_t *
+ * @param sr ip6_sr_header_t *
+ *
+ * @return retval int
+ */
 static int
 sr_validate_hmac (ip6_sr_main_t * sm, ip6_header_t * ip, ip6_sr_header_t * sr)
 {
@@ -2215,6 +2428,16 @@ sr_validate_hmac (ip6_sr_main_t * sm, ip6_header_t * ip, ip6_sr_header_t * sr)
   return memcmp (signature, addrp, SHA256_DIGEST_LENGTH);
 }
 
+/**
+ * @brief SR local node
+ * @node sr-local
+ *
+ * @param vm vlib_main_t *
+ * @param node vlib_node_runtime_t *
+ * @param from_frame vlib_frame_t *
+ *
+ * @return from_frame->n_vectors uword
+ */
 static uword
 sr_local (vlib_main_t * vm,
 	  vlib_node_runtime_t * node, vlib_frame_t * from_frame)
@@ -2648,7 +2871,15 @@ VLIB_NODE_FUNCTION_MULTIARCH (sr_local_node, sr_local)
   return &sr_main;
 }
 
-
+/**
+ * @brief CLI parser for SR fix destination rewrite node
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 set_ip6_sr_rewrite_fn (vlib_main_t * vm,
 		       unformat_input_t * input, vlib_cli_command_t * cmd)
@@ -2711,6 +2942,11 @@ VLIB_CLI_COMMAND (set_ip6_sr_rewrite, static) = {
 };
 /* *INDENT-ON* */
 
+/**
+ * @brief Register a callback routine to set next0 in sr_local
+ *
+ * @param cb void *
+ */
 void
 vnet_register_sr_app_callback (void *cb)
 {
@@ -2719,6 +2955,9 @@ vnet_register_sr_app_callback (void *cb)
   sm->sr_local_cb = cb;
 }
 
+/**
+ * @brief Test routine for validation of HMAC
+ */
 static clib_error_t *
 test_sr_hmac_validate_fn (vlib_main_t * vm,
 			  unformat_input_t * input, vlib_cli_command_t * cmd)
@@ -2746,6 +2985,17 @@ VLIB_CLI_COMMAND (test_sr_hmac_validate, static) = {
 };
 /* *INDENT-ON* */
 
+/**
+ * @brief Add or Delete HMAC key
+ *
+ * @param sm ip6_sr_main_t *
+ * @param key_id u32
+ * @param shared_secret u8 *
+ * @param is_del u8
+ *
+ * @return retval i32
+ */
+// $$$ fixme shouldn't return i32
 i32
 sr_hmac_add_del_key (ip6_sr_main_t * sm, u32 key_id, u8 * shared_secret,
 		     u8 is_del)
@@ -2844,7 +3094,15 @@ VLIB_CLI_COMMAND (sr_hmac, static) = {
 };
 /* *INDENT-ON* */
 
-
+/**
+ * @brief CLI parser for show HMAC key shared secrets
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 show_sr_hmac_fn (vlib_main_t * vm,
 		 unformat_input_t * input, vlib_cli_command_t * cmd)
@@ -2869,6 +3127,15 @@ VLIB_CLI_COMMAND (show_sr_hmac, static) = {
 };
 /* *INDENT-ON* */
 
+/**
+ * @brief Test for SR debug flag
+ *
+ * @param vm vlib_main_t *
+ * @param input unformat_input_t *
+ * @param cmd vlib_cli_command_t *
+ *
+ * @return error clib_error_t *
+ */
 static clib_error_t *
 test_sr_debug_fn (vlib_main_t * vm,
 		  unformat_input_t * input, vlib_cli_command_t * cmd)
diff --git a/vnet/vnet/sr/sr.h b/vnet/vnet/sr/sr.h
index 1ac70bd8de9..bd8fa8ebdc0 100644
--- a/vnet/vnet/sr/sr.h
+++ b/vnet/vnet/sr/sr.h
@@ -12,6 +12,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * @file
+ * @brief Segment Routing header
+ *
+ * @note sr_replicate only works using DPDK today
+ */
 #ifndef included_vnet_sr_h
 #define included_vnet_sr_h
 
@@ -28,163 +34,203 @@
 #include <openssl/opensslv.h>
 #include <openssl/hmac.h>
 
+/**
+ *    @brief Segment Route tunnel key
+ */
 typedef struct
 {
   ip6_address_t src;
   ip6_address_t dst;
 } ip6_sr_tunnel_key_t;
 
+/**
+ * @brief Segment Route tunnel
+ */
 typedef struct
 {
-  /* src, dst address */
+  /** src, dst address */
   ip6_sr_tunnel_key_t key;
 
-  /* optional tunnel name */
+  /** Pptional tunnel name */
   u8 *name;
 
-  /* mask width for FIB entry */
+  /** Mask width for FIB entry */
   u32 dst_mask_width;
 
-  /* first hop, to save 1 elt in the segment list */
+  /** First hop, to save 1 elt in the segment list */
   ip6_address_t first_hop;
 
-  /* Fib indices */
+  /** RX Fib index */
   u32 rx_fib_index;
+  /** TX Fib index */
   u32 tx_fib_index;
 
-  /* The actual ip6 sr header */
+  /** The actual ip6 SR header */
   u8 *rewrite;
 
-  /* Indicates that this tunnel is part of a policy comprising
-     of multiple tunnels. */
+  /** Indicates that this tunnel is part of a policy comprising
+     of multiple tunnels. If == ~0 tunnel is not part of a policy */
   u32 policy_index;
 } ip6_sr_tunnel_t;
 
+/**
+ * @brief Shared secret for keyed-hash message authentication code (HMAC).
+ */
 typedef struct
 {
   u8 *shared_secret;
 } ip6_sr_hmac_key_t;
 
+/**
+ * @brief Args required for add/del tunnel.
+ *
+ * Else we end up passing a LOT of parameters around.
+ */
 typedef struct
 {
-  /* Key (header imposition case) */
+  /** Key (header imposition case) */
   ip6_address_t *src_address;
   ip6_address_t *dst_address;
   u32 dst_mask_width;
   u32 rx_table_id;
   u32 tx_table_id;
 
-  /* optional name argument - for referencing SR tunnel/policy by name */
+  /** optional name argument - for referencing SR tunnel/policy by name */
   u8 *name;
 
-  /* optional policy name */
+  /** optional policy name */
   u8 *policy_name;
 
-  /* segment list, when inserting an ip6 SR header */
+  /** segment list, when inserting an ip6 SR header */
   ip6_address_t *segments;
 
-  /*
+  /**
    * "Tag" list, aka segments inserted at the end of the list,
    * past last_seg
    */
   ip6_address_t *tags;
 
-  /* Shared secret => generate SHA-256 HMAC security fields */
+  /** Shared secret => generate SHA-256 HMAC security fields */
   u8 *shared_secret;
 
-  /* Flags, e.g. cleanup, policy-list flags */
+  /** Flags, e.g. cleanup, policy-list flags */
   u16 flags_net_byte_order;
 
-  /* Delete the tunnnel? */
+  /** Delete the tunnnel? */
   u8 is_del;
 } ip6_sr_add_del_tunnel_args_t;
 
+/**
+ * @brief Args for creating a policy.
+ *
+ * Typically used for multicast replication.
+ * ie a multicast address can be associated with a policy,
+ * then replicated across a number of unicast SR tunnels.
+ */
 typedef struct
 {
-  /* policy name */
+  /** policy name */
   u8 *name;
 
-  /* tunnel names */
+  /** tunnel names */
   u8 **tunnel_names;
 
-  /* Delete the policy? */
+  /** Delete the policy? */
   u8 is_del;
 } ip6_sr_add_del_policy_args_t;
 
-
+/**
+ * @brief Segment Routing policy.
+ *
+ * Typically used for multicast replication.
+ * ie a multicast address can be associated with a policy,
+ * then replicated across a number of unicast SR tunnels.
+ */
 typedef struct
 {
-  /* name of policy */
+  /** name of policy */
   u8 *name;
 
-  /* vector to SR tunnel index */
+  /** vector to SR tunnel index */
   u32 *tunnel_indices;
 
 } ip6_sr_policy_t;
 
+/**
+ * @brief Args for mapping of multicast address to policy name.
+ *
+ * Typically used for multicast replication.
+ * ie a multicast address can be associated with a policy,
+ * then replicated across a number of unicast SR tunnels.
+ */
 typedef struct
 {
-  /* multicast IP6 address */
+  /** multicast IP6 address */
   ip6_address_t *multicast_address;
 
-  /* name of policy to map to */
+  /** name of policy to map to */
   u8 *policy_name;
 
-  /* Delete the mapping */
+  /** Delete the mapping */
   u8 is_del;
 
 } ip6_sr_add_del_multicastmap_args_t;
 
+/**
+ * @brief Segment Routing state.
+ */
 typedef struct
 {
-  /* pool of tunnel instances, sr entry only */
+  /** pool of tunnel instances, sr entry only */
   ip6_sr_tunnel_t *tunnels;
 
-  /* find an sr "tunnel" by its outer-IP src/dst */
+  /** find an sr "tunnel" by its outer-IP src/dst */
   uword *tunnel_index_by_key;
 
-  /* find an sr "tunnel" by its name */
+  /** find an sr "tunnel" by its name */
   uword *tunnel_index_by_name;
 
-  /* policy pool */
+  /** policy pool */
   ip6_sr_policy_t *policies;
 
-  /* find a policy by name */
+  /** find a policy by name */
   uword *policy_index_by_policy_name;
 
-  /* multicast address to policy mapping */
+  /** multicast address to policy mapping */
   uword *policy_index_by_multicast_address;
 
-  /* ip6-lookup next index for imposition FIB entries */
+  /** ip6-lookup next index for imposition FIB entries */
   u32 ip6_lookup_sr_next_index;
 
-  /* hmac key id by shared secret */
+  /** hmac key id by shared secret */
   uword *hmac_key_by_shared_secret;
 
-  /* ip6-rewrite next index for reinstalling the original dst address */
+  /** ip6-rewrite next index for reinstalling the original dst address */
   u32 ip6_rewrite_sr_next_index;
 
-  /* ip6-replicate next index for multicast tunnel */
+  /** ip6-replicate next index for multicast tunnel */
   u32 ip6_lookup_sr_replicate_index;
 
-  /* application API callback */
+  /** application API callback */
   void *sr_local_cb;
 
-  /* validate hmac keys */
+  /** validate hmac keys */
   u8 validate_hmac;
 
-  /* pool of hmac keys */
+  /** pool of hmac keys */
   ip6_sr_hmac_key_t *hmac_keys;
 
-  /* Openssl vbls */
+  /** Openssl var */
   EVP_MD *md;
+  /** Openssl var */
   HMAC_CTX *hmac_ctx;
 
-  /* enable debug spew */
+  /** enable debug spew */
   u8 is_debug;
 
-  /* convenience */
+  /** convenience */
   vlib_main_t *vlib_main;
+  /** convenience */
   vnet_main_t *vnet_main;
 } ip6_sr_main_t;
 
diff --git a/vnet/vnet/sr/sr_packet.h b/vnet/vnet/sr/sr_packet.h
index fc0d5eec3c1..179b94c2dc7 100644
--- a/vnet/vnet/sr/sr_packet.h
+++ b/vnet/vnet/sr/sr_packet.h
@@ -20,8 +20,11 @@
  * limitations under the License.
  */
 
-/*
- *   The Segment Routing Header (SRH) is defined as follows:
+/**
+ *  @file
+ *  @brief The Segment Routing Header (SRH).
+ *
+ *  The Segment Routing Header (SRH) is defined in the diagram below.
  *
  *
  *     0                   1                   2                   3
@@ -168,43 +171,51 @@
 #endif
 
 #define ROUTING_HEADER_TYPE_SR    4
-
+/**
+    @brief SR header struct.
+*/
 typedef struct
 {
-  /* Protocol for next header. */
+  /** Protocol for next header. */
   u8 protocol;
-  /*
+
+  /**
    * Length of routing header in 8 octet units,
    * not including the first 8 octets
    */
   u8 length;
 
-  /* Type of routing header; type 4 = segement routing */
+  /** Type of routing header; type 4 = segement routing */
   u8 type;
 
-  /* Next segment in the segment list */
+  /** Next segment in the segment list */
   u8 segments_left;
 
-  /*
+  /**
    * Policy list pointer: offset in the SRH of the policy
    * list - in 16-octet units - not including the first 8 octets.
    */
   u8 first_segment;
 
-  /* Flag bits */
+  /** Flag bits */
 #define IP6_SR_HEADER_FLAG_CLEANUP    (0x8000)
+  /** Flag bits */
 #define IP6_SR_HEADER_FLAG_PROTECTED  (0x4000)
+  /** Flag bits */
 #define IP6_SR_HEADER_FLAG_RESERVED   (0x3000)
-
+  /** Flag bits */
 #define IP6_SR_HEADER_FLAG_PL_ELT_NOT_PRESENT (0x0)
+    /** Flag bits */
 #define IP6_SR_HEADER_FLAG_PL_ELT_INGRESS_PE (0x1)
+    /** Flag bits */
 #define IP6_SR_HEADER_FLAG_PL_ELT_EGRESS_PE (0x2)
+    /** Flag bits */
 #define IP6_SR_HEADER_FLAG_PL_ELT_ORIG_SRC_ADDR (0x3)
-  /* values 0x4 - 0x7 are reserved */
+  /** values 0x4 - 0x7 are reserved */
   u16 flags;
   u8 hmac_key;
 
-  /* The segment + policy list elts */
+  /** The segment + policy list elts */
   ip6_address_t segments[0];
 } __attribute__ ((packed)) ip6_sr_header_t;
 
@@ -214,7 +225,7 @@ ip6_sr_policy_list_shift_from_index (int pl_index)
   return (-3 * pl_index) + 12;
 }
 
-/* pl_index is one-origined, to match the text above */
+/** pl_index is one-origined */
 static inline int
 ip6_sr_policy_list_flags (u16 flags_host_byte_order, int pl_index)
 {
diff --git a/vnet/vnet/sr/sr_replicate.c b/vnet/vnet/sr/sr_replicate.c
index 4711ff1a1ed..37c39442efd 100644
--- a/vnet/vnet/sr/sr_replicate.c
+++ b/vnet/vnet/sr/sr_replicate.c
@@ -105,6 +105,9 @@ _(NO_BUFFERS, "error allocating buffers for replicas") \
 _(NO_REPLICAS, "no replicas were needed") \
 _(NO_BUFFER_DROPS, "sr no buffer drops")
 
+/**
+ * @brief Struct for SR replicate errors
+ */
 typedef enum
 {
 #define _(sym,str) SR_REPLICATE_ERROR_##sym,
@@ -113,6 +116,9 @@ typedef enum
     SR_REPLICATE_N_ERROR,
 } sr_replicate_error_t;
 
+/**
+ * @brief Error strings for SR replicate
+ */
 static char *sr_replicate_error_strings[] = {
 #define _(sym,string) string,
   foreach_sr_replicate_error