@2653713 Add an ip_route_set() method that takes a 'type' hint.

eos/inline/types/ip_route.h

@@ -6,6 +6,24 @@
 
 namespace eos {
 
+inline std::ostream&
+operator<<(std::ostream& os, const ip_route_action_t & enum_val) {
+   if (enum_val==IP_ROUTE_ACTION_NULL) {
+      os << "IP_ROUTE_ACTION_NULL";
+   } else if (enum_val==IP_ROUTE_ACTION_FORWARD) {
+      os << "IP_ROUTE_ACTION_FORWARD";
+   } else if (enum_val==IP_ROUTE_ACTION_DROP) {
+      os << "IP_ROUTE_ACTION_DROP";
+   } else if (enum_val==IP_ROUTE_ACTION_NEXTHOP_GROUP) {
+      os << "IP_ROUTE_ACTION_NEXTHOP_GROUP";
+   } else {
+      os << "Unknown value";
+   }
+   return os;
+}
+
+
+
 inline ip_route_key_t::ip_route_key_t() :
       prefix_(), preference_(1) {
 }

eos/ip_route.h

@@ -97,17 +97,42 @@ class EOS_SDK_PUBLIC ip_route_mgr {
 
    // Route management functions
 
-   /// Gets a static route, or panics if the route key does not exist.
+   /**
+    * Gets the IP route with the corresponding ip_route_key_t. Returns
+    * an empty ip_route_t() if no matching route is found.
+    */
    virtual ip_route_t ip_route(ip_route_key_t const &) = 0;
-   /// Inserts or updates a static route into the switch configuration.
+   /**
+    * Inserts or updates a static route into the switch configuration.
+    */
    virtual void ip_route_set(ip_route_t const &) = 0;
+   /**
+    * Performs the same operation as `ip_route_set`, but lets an agent
+    * hint what type of vias will be attached to this route. For
+    * example, if the agent knows it will be adding nexthop group vias
+    * to this route, it can pass `eos::IP_ROUTE_ACTION_NEXTHOP_GROUP`,
+    * which allows EOS to more efficiently program routes. Routes are
+    * created by 'forward' routes if no additional information is
+    * provided.
+    */
+   virtual void ip_route_set(ip_route_t const &,
+                             ip_route_action_t expected_type) = 0;
    /// Removes all ECMP vias matching the route key, and the route itself.
    virtual void ip_route_del(ip_route_key_t const &) = 0;
 
    /**
     * Adds a via to an ip_route_t.
-    * Will call panic() if the corresponding route does not match the
-    * currently configured tag.
+    *
+    * A via is associated with an ip_route_t by their `ip_route_key_t`
+    * attributes. If an agent adds multiple vias with a hop or intf set,
+    * EOS will ECMP across these "forward" routes. If it programs a
+    * 'drop' via (by setting the intf attribute to Null0), all other
+    * vias attached to this route will be removed, and all traffic on
+    * this route will be dropped. Similarly, if the nexthop_group
+    * attribute is set, all other vias with the same `ip_route_key_t`
+    * will be removed, and the new nexthop group via will be
+    * programmed in their place. This function will call panic() if the
+    * route does not match the currently configured tag.
     *
     * @throws eos::invalid_argument_error If the passed via has no IP
     * address, interface or nexthop group set.

eos/types/ip_route.h

@@ -16,6 +16,21 @@ typedef uint32_t ip_route_tag_t;
 typedef uint8_t ip_route_preference_t;
 typedef uint32_t ip_route_metric_t;
 
+/**
+ * The type of the ip_route_t. This is determined by the ip_route_via_t's attached
+ * to this route.
+ */
+enum ip_route_action_t {
+   IP_ROUTE_ACTION_NULL,
+   IP_ROUTE_ACTION_FORWARD,
+   IP_ROUTE_ACTION_DROP,
+   IP_ROUTE_ACTION_NEXTHOP_GROUP,
+};
+/**
+ * Appends a string representation of enum ip_route_action_t value to the ostream.
+ */
+std::ostream& operator<<(std::ostream& os, const ip_route_action_t & enum_val);
+
 /** An IP route key, consisting of a prefix and preference. */
 class EOS_SDK_PUBLIC ip_route_key_t {
  public:

ip_route.cpp

@@ -54,6 +54,11 @@ class ip_route_mgr_impl : public ip_route_mgr {
       // TODO: No op impl.
    }
 
+   void ip_route_set(const ip_route_t & route,
+                     ip_route_action_t expected_type) {
+      // TODO: No op impl.
+   }
+
    void ip_route_del(const ip_route_key_t & route_key) {
       // TODO: No op impl.
    }