VPP-166 Documentation changes for ip4.h/lookup.h
[vpp.git] / vnet / vnet / ip / ip4.h
index 6b8fd59..9a54300 100644 (file)
@@ -43,6 +43,7 @@
 #include <vnet/ip/ip4_mtrie.h>
 #include <vnet/ip/ip4_packet.h>
 #include <vnet/ip/lookup.h>
+#include <vnet/ip/ip_feature_registration.h>
 
 typedef struct ip4_fib_t {
   /* Hash table for each prefix length mapping. */
@@ -101,78 +102,119 @@ typedef struct {
   uword function_opaque;
 } ip4_add_del_interface_address_callback_t;
 
-typedef enum {
-  /* First check access list to either permit or deny this
-     packet based on classification. */
-  IP4_RX_FEATURE_CHECK_ACCESS,
-
-  /* RPF check: verify that source address is reachable via
-     RX interface or via any interface. */
-  IP4_RX_FEATURE_SOURCE_CHECK_REACHABLE_VIA_RX,
-  IP4_RX_FEATURE_SOURCE_CHECK_REACHABLE_VIA_ANY,
-
-  /* IPSec */
-  IP4_RX_FEATURE_IPSEC,
-
-  /* vPath forwarding: won't return to call next feature
-     so any feature needed before vPath forwarding must be prior
-     to this entry */
-  IP4_RX_FEATURE_VPATH,
-
-  /* Must be last: perform forwarding lookup. */
-  IP4_RX_FEATURE_LOOKUP,
-
-  IP4_N_RX_FEATURE,
-} ip4_rx_feature_type_t;
+/**
+ * @brief IPv4 main type.
+ *
+ * State of IPv4 VPP processing including:
+ * - FIBs
+ * - Feature indices used in feature topological sort
+ * - Feature node run time references
+ */
 
 typedef struct ip4_main_t {
   ip_lookup_main_t lookup_main;
 
-  /* Vector of FIBs. */
+  /** Vector of FIBs. */
   ip4_fib_t * fibs;
 
   u32 fib_masks[33];
 
-  /* Table index indexed by software interface. */
+  /** Table index indexed by software interface. */
   u32 * fib_index_by_sw_if_index;
 
-  /* Hash table mapping table id to fib index.
+  /** Hash table mapping table id to fib index.
      ID space is not necessarily dense; index space is dense. */
   uword * fib_index_by_table_id;
 
-  /* Vector of functions to call when routes are added/deleted. */
+  /** Vector of functions to call when routes are added/deleted. */
   ip4_add_del_route_callback_t * add_del_route_callbacks;
 
-  /* Hash table mapping interface route rewrite adjacency index by sw if index. */
+  /** Hash table mapping interface route rewrite adjacency index by sw if index. */
   uword * interface_route_adj_index_by_sw_if_index;
 
-  /* Functions to call when interface address changes. */
+  /** Functions to call when interface address changes. */
   ip4_add_del_interface_address_callback_t * add_del_interface_address_callbacks;
 
-  /* Template used to generate IP4 ARP packets. */
+  /** Template used to generate IP4 ARP packets. */
   vlib_packet_template_t ip4_arp_request_packet_template;
 
-  /* Seed for Jenkins hash used to compute ip4 flow hash. */
+  /** Feature path configuration lists */
+  vnet_ip_feature_registration_t * next_uc_feature;
+  vnet_ip_feature_registration_t * next_mc_feature;
+
+  /** Built-in unicast feature path indice, see @ref ip_feature_init_cast()  */
+  u32 ip4_unicast_rx_feature_check_access;
+  /** Built-in unicast feature path indice, see @ref ip_feature_init_cast()  */
+  u32 ip4_unicast_rx_feature_source_reachable_via_rx;
+  /** Built-in unicast feature path indice, see @ref ip_feature_init_cast()  */
+  u32 ip4_unicast_rx_feature_source_reachable_via_any;
+  /** Built-in unicast feature path indice, see @ref ip_feature_init_cast()  */
+  u32 ip4_unicast_rx_feature_policer_classify;
+  /** Built-in unicast feature path indice, see @ref ip_feature_init_cast()  */
+  u32 ip4_unicast_rx_feature_ipsec;
+  /** Built-in unicast feature path indice, see @ref ip_feature_init_cast()  */
+  u32 ip4_unicast_rx_feature_vpath;
+  /** Built-in unicast feature path indice, see @ref ip_feature_init_cast()  */
+  u32 ip4_unicast_rx_feature_lookup;
+  /** Built-in unicast feature path indice, see @ref ip_feature_init_cast()  */
+  u32 ip4_unicast_rx_feature_source_and_port_range_check;
+
+  /** Built-in multicast feature path indices */
+  u32 ip4_multicast_rx_feature_vpath;
+  /** Built-in multicast feature path indices */
+  u32 ip4_multicast_rx_feature_lookup;
+
+  /** Save results for show command */
+  char ** feature_nodes[VNET_N_CAST];
+
+  /** Seed for Jenkins hash used to compute ip4 flow hash. */
   u32 flow_hash_seed;
 
+  /** @brief Template information for VPP generated packets */
   struct {
-    /* TTL to use for host generated packets. */
+    /** TTL to use for host generated packets. */
     u8 ttl;
 
-    /* TOS byte to use for host generated packets. */
+    /** TOS byte to use for host generated packets. */
     u8 tos;
 
     u8 pad[2];
   } host_config;
 } ip4_main_t;
 
-/* Global ip4 main structure. */
+/** Global ip4 main structure. */
 extern ip4_main_t ip4_main;
 
-/* Global ip4 input node.  Errors get attached to ip4 input node. */
+#define VNET_IP4_UNICAST_FEATURE_INIT(x,...)                    \
+  __VA_ARGS__ vnet_ip_feature_registration_t uc_##x;            \
+static void __vnet_add_feature_registration_uc_##x (void)       \
+  __attribute__((__constructor__)) ;                            \
+static void __vnet_add_feature_registration_uc_##x (void)       \
+{                                                               \
+  ip4_main_t * im = &ip4_main;                                  \
+  uc_##x.next = im->next_uc_feature;                            \
+  im->next_uc_feature = &uc_##x;                                \
+}                                                               \
+__VA_ARGS__ vnet_ip_feature_registration_t uc_##x 
+
+#define VNET_IP4_MULTICAST_FEATURE_INIT(x,...)                  \
+  __VA_ARGS__ vnet_ip_feature_registration_t mc_##x;            \
+static void __vnet_add_feature_registration_mc_##x (void)       \
+  __attribute__((__constructor__)) ;                            \
+static void __vnet_add_feature_registration_mc_##x (void)       \
+{                                                               \
+  ip4_main_t * im = &ip4_main;                                  \
+  mc_##x.next = im->next_mc_feature;                            \
+  im->next_mc_feature = &mc_##x;                                \
+}                                                               \
+__VA_ARGS__ vnet_ip_feature_registration_t mc_##x 
+
+
+/** Global ip4 input node.  Errors get attached to ip4 input node. */
 extern vlib_node_registration_t ip4_input_node;
 extern vlib_node_registration_t ip4_lookup_node;
 extern vlib_node_registration_t ip4_rewrite_node;
+extern vlib_node_registration_t ip4_rewrite_local_node;
 extern vlib_node_registration_t ip4_arp_node;
 
 u32 ip4_fib_lookup_with_table (ip4_main_t * im, u32 fib_index, ip4_address_t * dst,
@@ -218,13 +260,16 @@ ip4_unaligned_destination_matches_route (ip4_main_t * im,
                                         uword dest_length)
 { return 0 == ((clib_mem_unaligned (&key->data_u32, u32) ^ dest->data_u32) & im->fib_masks[dest_length]); }
 
-always_inline void
+always_inline int
 ip4_src_address_for_packet (ip4_main_t * im, vlib_buffer_t * p, ip4_address_t * src, u32 sw_if_index)
 {
   ip_lookup_main_t * lm = &im->lookup_main;
   ip_interface_address_t * ia = ip_interface_address_for_packet (lm, p, sw_if_index);
+  if (ia == NULL)
+    return -1;
   ip4_address_t * a = ip_interface_address_get_address (lm, ia);
   *src = a[0];
+  return 0;
 }
 
 /* Find interface address which matches destination. */
@@ -293,6 +338,28 @@ typedef struct {
   u32 n_add_adj;
 } ip4_add_del_route_args_t;
 
+/**
+ * \brief Get or create an IPv4 fib.
+ *
+ * Get or create an IPv4 fib with the provided fib ID or index.
+ * The fib ID is a possibly-sparse user-defined value while
+ * the fib index defines the position of the fib in the fib vector.
+ *
+ * \param im
+ *      ip4_main pointer.
+ * \param table_index_or_id
+ *      The table index if \c IP4_ROUTE_FLAG_FIB_INDEX bit is set in \p flags.
+ *      Otherwise, when set to \c ~0, an arbitrary and unused fib ID is picked
+ *      and can be retrieved with \c ret->table_id.
+ *      Otherwise, the fib ID to be used to retrieve or create the desired fib.
+ * \param flags
+ *      Indicates whether \p table_index_or_id is the fib index or ID.
+ *      When the bit \c IP4_ROUTE_FLAG_FIB_INDEX is set, \p table_index_or_id
+ *      is considered as the fib index, and the fib ID otherwise.
+ * \returns A pointer to the retrieved or created fib.
+ *
+ * \remark When getting a fib with the fib index, the fib MUST already exist.
+ */
 ip4_fib_t *
 find_ip4_fib_by_table_index_or_id (ip4_main_t * im, 
                                    u32 table_index_or_id, u32 flags);
@@ -308,6 +375,13 @@ void ip4_add_del_route_next_hop (ip4_main_t * im,
                                  u32 next_hop_weight, u32 adj_index, 
                                  u32 explicit_fib_index);
 
+u32
+ip4_route_get_next_hop_adj (ip4_main_t * im,
+                           u32 fib_index,
+                           ip4_address_t *next_hop,
+                           u32 next_hop_sw_if_index,
+                           u32 explicit_fib_index);
+
 void *
 ip4_get_route (ip4_main_t * im,
               u32 fib_index_or_table_id,
@@ -339,6 +413,10 @@ void ip4_adjacency_set_interface_route (vnet_main_t * vnm,
                                        u32 sw_if_index,
                                        u32 if_address_index);
 
+ip4_address_t *
+ip4_interface_first_address (ip4_main_t * im, u32 sw_if_index,
+                             ip_interface_address_t ** result_ia);
+
 /* Send an ARP request to see if given destination is reachable on given interface. */
 clib_error_t *
 ip4_probe_neighbor (vlib_main_t * vm, ip4_address_t * dst, u32 sw_if_index);
@@ -346,10 +424,6 @@ ip4_probe_neighbor (vlib_main_t * vm, ip4_address_t * dst, u32 sw_if_index);
 clib_error_t *
 ip4_set_arp_limit (u32 arp_limit);
 
-uword
-ip4_tcp_register_listener (vlib_main_t * vm,
-                          u16 dst_port,
-                          u32 next_node_index);
 uword
 ip4_udp_register_listener (vlib_main_t * vm,
                           u16 dst_port,