VPP Object Model (VOM)

The VOM is a C++ library for use by clients/agents of VPP for programming
state. It uses the binary APIs to do so. Various other common client side
functions are also provided. Please see om.hpp for a more detailed description.

Change-Id: Ib756bfe99817093815a9e26ccf464aa5583fc523
Signed-off-by: Neale Ranns <neale.ranns@cisco.com>
Co-authored-by: Mohsin Kazmi <sykazmi@cisco.com>

1 files changed, 1002 insertions, 0 deletions

diff --git a/src/vpp-api/vom/interface.hpp b/src/vpp-api/vom/interface.hpp
new file mode 100644
index 00000000000..8863bc94868
--- /dev/null
+++ b/src/vpp-api/vom/interface.hpp
@@ -0,0 +1,1002 @@
+/*
+ * Copyright (c) 2017 Cisco and/or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __VOM_INTERFACE_H__
+#define __VOM_INTERFACE_H__
+
+#include "vom/dump_cmd.hpp"
+#include "vom/enum_base.hpp"
+#include "vom/event_cmd.hpp"
+#include "vom/hw.hpp"
+#include "vom/inspect.hpp"
+#include "vom/object_base.hpp"
+#include "vom/om.hpp"
+#include "vom/prefix.hpp"
+#include "vom/route_domain.hpp"
+#include "vom/rpc_cmd.hpp"
+#include "vom/singular_db.hpp"
+
+#include <vapi/af_packet.api.vapi.hpp>
+#include <vapi/interface.api.vapi.hpp>
+#include <vapi/stats.api.vapi.hpp>
+#include <vapi/tap.api.vapi.hpp>
+#include <vapi/vapi.hpp>
+#include <vapi/vpe.api.vapi.hpp>
+
+namespace VOM {
+/**
+ * A representation of an interface in VPP
+ */
+class interface : public object_base
+{
+public:
+  /**
+   * The key for interface's key
+   */
+  typedef std::string key_type;
+
+  /**
+   * The iterator type
+   */
+  typedef singular_db<const std::string, interface>::const_iterator
+    const_iterator_t;
+
+  /**
+   * An interface type
+   */
+  struct type_t : enum_base<type_t>
+  {
+    /**
+     * Unkown type
+     */
+    const static type_t UNKNOWN;
+    /**
+     * A brideged Virtual interface (aka SVI or IRB)
+     */
+    const static type_t BVI;
+    /**
+     * VXLAN interface
+     */
+    const static type_t VXLAN;
+    /**
+     * Ethernet interface type
+     */
+    const static type_t ETHERNET;
+    /**
+     * AF-Packet interface type
+     */
+    const static type_t AFPACKET;
+    /**
+     * loopback interface type
+     */
+    const static type_t LOOPBACK;
+    /**
+     * Local interface type (specific to VPP)
+     */
+    const static type_t LOCAL;
+    /**
+     * TAP interface type
+     */
+    const static type_t TAP;
+
+    /**
+     * Convert VPP's name of the interface to a type
+     */
+    static type_t from_string(const std::string& str);
+
+  private:
+    /**
+     * Private constructor taking the value and the string name
+     */
+    type_t(int v, const std::string& s);
+  };
+
+  /**
+   * The admin state of the interface
+   */
+  struct admin_state_t : enum_base<admin_state_t>
+  {
+    /**
+     * Admin DOWN state
+     */
+    const static admin_state_t DOWN;
+    /**
+     * Admin UP state
+     */
+    const static admin_state_t UP;
+
+    /**
+     * Convert VPP's numerical value to enum type
+     */
+    static admin_state_t from_int(uint8_t val);
+
+  private:
+    /**
+     * Private constructor taking the value and the string name
+     */
+    admin_state_t(int v, const std::string& s);
+  };
+
+  /**
+   * The oper state of the interface
+   */
+  struct oper_state_t : enum_base<oper_state_t>
+  {
+    /**
+     * Operational DOWN state
+     */
+    const static oper_state_t DOWN;
+    /**
+     * Operational UP state
+     */
+    const static oper_state_t UP;
+
+    /**
+     * Convert VPP's numerical value to enum type
+     */
+    static oper_state_t from_int(uint8_t val);
+
+  private:
+    /**
+     * Private constructor taking the value and the string name
+     */
+    oper_state_t(int v, const std::string& s);
+  };
+
+  /**
+   * Construct a new object matching the desried state
+   */
+  interface(const std::string& name, type_t type, admin_state_t state);
+  /**
+   * Construct a new object matching the desried state mapped
+   * to a specific route_domain
+   */
+  interface(const std::string& name,
+            type_t type,
+            admin_state_t state,
+            const route_domain& rd);
+  /**
+   * Destructor
+   */
+  virtual ~interface();
+
+  /**
+   * Copy Constructor
+   */
+  interface(const interface& o);
+
+  static const_iterator_t cbegin();
+  static const_iterator_t cend();
+
+  /**
+   * Return the matching'singular' of the interface
+   */
+  std::shared_ptr<interface> singular() const;
+
+  /**
+   * convert to string format for debug purposes
+   */
+  virtual std::string to_string(void) const;
+
+  /**
+   * Return VPP's handle to this object
+   */
+  const handle_t& handle() const;
+
+  /**
+   * Return the interface type
+   */
+  const type_t& type() const;
+
+  /**
+   * Return the interface type
+   */
+  const std::string& name() const;
+
+  /**
+   * Return the interface type
+   */
+  const key_type& key() const;
+
+  /**
+   * Return the L2 Address
+   */
+  const l2_address_t& l2_address() const;
+
+  /**
+   * Set the L2 Address
+   */
+  void set(const l2_address_t& addr);
+
+  /**
+   * Set the operational state of the interface, as reported by VPP
+   */
+  void set(const oper_state_t& state);
+
+  /**
+   * A base class for interface Create commands
+   */
+  template <typename MSG>
+  class create_cmd : public rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>
+  {
+  public:
+    create_cmd(HW::item<handle_t>& item, const std::string& name)
+      : rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>(item)
+      , m_name(name)
+    {
+    }
+
+    /**
+     * Destructor
+     */
+    virtual ~create_cmd() = default;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    virtual bool operator==(const create_cmd& o) const
+    {
+      return (m_name == o.m_name);
+    }
+
+    /**
+     * Indicate the succeeded, when the HW Q is disabled.
+     */
+    void succeeded()
+    {
+      rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>::succeeded();
+      interface::add(m_name, this->item());
+    }
+
+    virtual vapi_error_e operator()(MSG& reply)
+    {
+      int sw_if_index = reply.get_response().get_payload().sw_if_index;
+      int retval = reply.get_response().get_payload().retval;
+
+      VOM_LOG(log_level_t::DEBUG) << this->to_string() << " " << retval;
+
+      rc_t rc = rc_t::from_vpp_retval(retval);
+      handle_t handle = handle_t::INVALID;
+
+      if (rc_t::OK == rc) {
+        handle = sw_if_index;
+      }
+
+      HW::item<handle_t> res(handle, rc);
+
+      this->fulfill(res);
+
+      return (VAPI_OK);
+    }
+
+  protected:
+    /**
+     * The name of the interface to be created
+     */
+    const std::string& m_name;
+  };
+
+  /**
+   * A command class to create Loopback interfaces in VPP
+   */
+  class loopback_create_cmd : public create_cmd<vapi::Create_loopback>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     * and the name of the interface to create
+     */
+    loopback_create_cmd(HW::item<handle_t>& item, const std::string& name);
+    ~loopback_create_cmd() = default;
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+  };
+
+  /**
+   * A command class to create af_packet interfaces in VPP
+   */
+  class af_packet_create_cmd : public create_cmd<vapi::Af_packet_create>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     * and the name of the interface to create
+     */
+    af_packet_create_cmd(HW::item<handle_t>& item, const std::string& name);
+    ~af_packet_create_cmd() = default;
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+  };
+
+  /**
+   * A command class to create TAP interfaces in VPP
+   */
+  class tap_create_cmd : public create_cmd<vapi::Tap_connect>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     * and the name of the interface to create
+     */
+    tap_create_cmd(HW::item<handle_t>& item, const std::string& name);
+    ~tap_create_cmd() = default;
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+  };
+
+  /**
+   * Base class for intterface Delete commands
+   */
+  template <typename MSG>
+  class delete_cmd : public rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>
+  {
+  public:
+    delete_cmd(HW::item<handle_t>& item, const std::string& name)
+      : rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>(item)
+      , m_name(name)
+    {
+    }
+
+    delete_cmd(HW::item<handle_t>& item)
+      : rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>(item)
+      , m_name()
+    {
+    }
+
+    /**
+     * Destructor
+     */
+    virtual ~delete_cmd() = default;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    virtual bool operator==(const delete_cmd& o) const
+    {
+      return (this->m_hw_item == o.m_hw_item);
+    }
+
+    /**
+     * Indicate the succeeded, when the HW Q is disabled.
+     */
+    void succeeded() {}
+
+  protected:
+    /**
+     * The name of the interface to be created
+     */
+    const std::string m_name;
+  };
+
+  /**
+   * A command class to delete loopback interfaces in VPP
+   */
+  class loopback_delete_cmd : public delete_cmd<vapi::Delete_loopback>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     */
+    loopback_delete_cmd(HW::item<handle_t>& item);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+  };
+
+  /**
+   * A command class to delete af-packet interfaces in VPP
+   */
+  class af_packet_delete_cmd : public delete_cmd<vapi::Af_packet_delete>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     * and the name of the interface to delete
+     */
+    af_packet_delete_cmd(HW::item<handle_t>& item, const std::string& name);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+  };
+
+  /**
+   * A command class to delete TAP interfaces in VPP
+   */
+  class tap_delete_cmd : public delete_cmd<vapi::Tap_delete>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     */
+    tap_delete_cmd(HW::item<handle_t>& item);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+  };
+
+  /**
+   * A command class to delete TAP interfaces in VPP
+   */
+  class set_tag
+    : public rpc_cmd<HW::item<handle_t>, rc_t, vapi::Sw_interface_tag_add_del>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     */
+    set_tag(HW::item<handle_t>& item, const std::string& name);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    bool operator==(const set_tag& i) const;
+
+  private:
+    /**
+     * The tag to add
+     */
+    const std::string m_name;
+  };
+
+  /**
+   * A cmd class that changes the admin state
+   */
+  class state_change_cmd : public rpc_cmd<HW::item<admin_state_t>,
+                                          rc_t,
+                                          vapi::Sw_interface_set_flags>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     * and the name handle of the interface whose state is to change
+     */
+    state_change_cmd(HW::item<admin_state_t>& s, const HW::item<handle_t>& h);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    bool operator==(const state_change_cmd& i) const;
+
+  private:
+    /**
+     * the handle of the interface to update
+     */
+    const HW::item<handle_t>& m_hdl;
+  };
+
+  /**
+   * A command class that binds an interface to an L3 table
+   */
+  class set_table_cmd : public rpc_cmd<HW::item<route::table_id_t>,
+                                       rc_t,
+                                       vapi::Sw_interface_set_table>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     * and the name handle of the interface whose table is to change
+     */
+    set_table_cmd(HW::item<route::table_id_t>& item,
+                  const l3_proto_t& proto,
+                  const HW::item<handle_t>& h);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    bool operator==(const set_table_cmd& i) const;
+
+  private:
+    /**
+     * the handle of the interface to update
+     */
+    const HW::item<handle_t>& m_hdl;
+
+    /**
+     * The L3 protocol of the table
+     */
+    l3_proto_t m_proto;
+  };
+
+  /**
+   * A command class that binds an interface to an L3 table
+   */
+  class set_mac_cmd : public rpc_cmd<HW::item<l2_address_t>,
+                                     rc_t,
+                                     vapi::Sw_interface_set_mac_address>
+  {
+  public:
+    /**
+     * Constructor taking the HW::item to update
+     * and the handle of the interface
+     */
+    set_mac_cmd(HW::item<l2_address_t>& item, const HW::item<handle_t>& h);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    bool operator==(const set_mac_cmd& i) const;
+
+  private:
+    /**
+     * the handle of the interface to update
+     */
+    const HW::item<handle_t>& m_hdl;
+  };
+
+  /**
+   * Forward declaration of the Event command
+   */
+  class events_cmd;
+
+  /**
+   * A class that listens to interface Events
+   */
+  class event_listener
+  {
+  public:
+    /**
+     * Default Constructor
+     */
+    event_listener();
+
+    /**
+     * Virtual function called on the listener when the command has data
+     * ready to process
+     */
+    virtual void handle_interface_event(events_cmd* cmd) = 0;
+
+    /**
+     * Return the HW::item representing the status
+     */
+    HW::item<bool>& status();
+
+  protected:
+    /**
+     * The status of the subscription
+     */
+    HW::item<bool> m_status;
+  };
+
+  /**
+   * A command class represents our desire to recieve interface events
+   */
+  class events_cmd
+    : public event_cmd<vapi::Want_interface_events, vapi::Sw_interface_event>
+  {
+  public:
+    /**
+     * Constructor taking the listner to notify
+     */
+    events_cmd(event_listener& el);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+
+    /**
+     * Retires the command - unsubscribe from the events.
+     */
+    void retire(connection& con);
+
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    bool operator==(const events_cmd& i) const;
+
+    /**
+     * Called when it's time to poke the listeners
+     */
+    void notify();
+
+  private:
+    /**
+     * The listeners to notify when data/events arrive
+     */
+    event_listener& m_listener;
+  };
+
+  /**
+   * Forward declaration of the stat command
+   */
+  class stats_cmd;
+
+  /**
+   * A class that listens to interface Stats
+   */
+  class stat_listener
+  {
+  public:
+    /**
+     * Default Constructor
+     */
+    stat_listener();
+
+    /**
+     * Virtual function called on the listener when the command has data
+     * ready to process
+     */
+    virtual void handle_interface_stat(stats_cmd* cmd) = 0;
+
+    /**
+     * Return the HW::item representing the status
+     */
+    HW::item<bool>& status();
+
+  protected:
+    /**
+     * The status of the subscription
+     */
+    HW::item<bool> m_status;
+  };
+
+  /**
+   * A command class represents our desire to recieve interface stats
+   */
+  class stats_cmd : public event_cmd<vapi::Want_per_interface_combined_stats,
+                                     vapi::Vnet_per_interface_combined_counters>
+  {
+  public:
+    /**
+     * Constructor taking the listner to notify
+     */
+    stats_cmd(stat_listener& el, const std::vector<handle_t>& interfaces);
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+
+    /**
+     * Retires the command - unsubscribe from the stats.
+     */
+    void retire(connection& con);
+
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    bool operator==(const stats_cmd& i) const;
+
+    /**
+     * Called when it's time to poke the listeners
+     */
+    void notify();
+
+  private:
+    /**
+     * The listeners to notify when data/stats arrive
+     */
+    stat_listener& m_listener;
+
+    std::vector<handle_t> m_swifindex;
+  };
+
+  /**
+   * A cmd class that Dumps all the Vpp interfaces
+   */
+  class dump_cmd : public VOM::dump_cmd<vapi::Sw_interface_dump>
+  {
+  public:
+    /**
+     * Default Constructor
+     */
+    dump_cmd();
+
+    /**
+     * Issue the command to VPP/HW
+     */
+    rc_t issue(connection& con);
+    /**
+     * convert to string format for debug purposes
+     */
+    std::string to_string() const;
+
+    /**
+     * Comparison operator - only used for UT
+     */
+    bool operator==(const dump_cmd& i) const;
+  };
+
+  /**
+   * The the singular instance of the interface in the object_base-Model
+   */
+  static std::shared_ptr<interface> find(const interface& temp);
+
+  /**
+   * The the singular instance of the interface in the object_base-Model
+   * by handle
+   */
+  static std::shared_ptr<interface> find(const handle_t& h);
+
+  /**
+   * The the singular instance of the interface in the object_base-Model
+   * by name
+   */
+  static std::shared_ptr<interface> find(const std::string& s);
+
+  /**
+   * Dump all interfaces into the stream provided
+   */
+  static void dump(std::ostream& os);
+
+  /**
+   * Factory method to construct a new interface from the VPP record
+   */
+  static std::unique_ptr<interface> new_interface(
+    const vapi_payload_sw_interface_details& vd);
+
+protected:
+  /**
+   * Construct an interface object with a handle and a HW address
+   */
+  interface(const handle_t& handle,
+            const l2_address_t& l2_address,
+            const std::string& name,
+            type_t type,
+            admin_state_t state);
+
+  /**
+   * The SW interface handle VPP has asigned to the interface
+   */
+  HW::item<handle_t> m_hdl;
+
+  /**
+   * Return the matching 'singular' of the interface
+   */
+  virtual std::shared_ptr<interface> singular_i() const;
+
+  /**
+   * release/remove an interface form the singular store
+   */
+  void release();
+
+  /**
+   * Virtual functions to construct an interface create commands.
+   * Overridden in derived classes like the sub_interface
+   */
+  virtual std::queue<cmd*>& mk_create_cmd(std::queue<cmd*>& cmds);
+
+  /**
+   * Virtual functions to construct an interface delete commands.
+   * Overridden in derived classes like the sub_interface
+   */
+  virtual std::queue<cmd*>& mk_delete_cmd(std::queue<cmd*>& cmds);
+
+  /**
+   * Sweep/reap the object if still stale
+   */
+  virtual void sweep(void);
+
+  /**
+   * A map of all interfaces key against the interface's name
+   */
+  static singular_db<const std::string, interface> m_db;
+
+  /**
+   * Add an interface to the DB keyed on handle
+   */
+  static void add(const std::string& name, const HW::item<handle_t>& item);
+
+  /**
+   * remove an interface from the DB keyed on handle
+   */
+  static void remove(const HW::item<handle_t>& item);
+
+private:
+  /**
+   * Class definition for listeners to OM events
+   */
+  class event_handler : public OM::listener, public inspect::command_handler
+  {
+  public:
+    event_handler();
+    virtual ~event_handler() = default;
+
+    /**
+     * Handle a populate event
+     */
+    void handle_populate(const client_db::key_t& key);
+
+    /**
+     * Handle a replay event
+     */
+    void handle_replay();
+
+    /**
+     * Show the object in the Singular DB
+     */
+    void show(std::ostream& os);
+
+    /**
+     * Get the sortable Id of the listener
+     */
+    dependency_t order() const;
+  };
+
+  static event_handler m_evh;
+
+  /**
+   * Commit the acculmulated changes into VPP. i.e. to a 'HW" write.
+   */
+  void update(const interface& obj);
+
+  /*
+   * It's the OM class that calls singular()
+   */
+  friend class OM;
+
+  /**
+   * It's the singular_db class that calls replay()
+   */
+  friend class singular_db<const std::string, interface>;
+
+  /**
+   * The interfaces name
+   */
+  const std::string m_name;
+
+  /**
+   * The interface type. clearly this cannot be changed
+   * once the interface has been created.
+   */
+  const type_t m_type;
+
+  /**
+   * shared pointer to the routeDoamin the interface is in.
+   * NULL is not mapped  - i.e. in eht default table
+   */
+  const std::shared_ptr<route_domain> m_rd;
+
+  /**
+   * The state of the interface
+   */
+  HW::item<admin_state_t> m_state;
+
+  /**
+   * HW state of the VPP table mapping
+   */
+  HW::item<route::table_id_t> m_table_id;
+
+  /**
+   * HW state of the L2 address
+   */
+  HW::item<l2_address_t> m_l2_address;
+
+  /**
+   * Operational state of the interface
+   */
+  oper_state_t m_oper;
+
+  /**
+   * A map of all interfaces keyed against VPP's handle
+   */
+  static std::map<handle_t, std::weak_ptr<interface>> m_hdl_db;
+
+  /**
+   * replay the object to create it in hardware
+   */
+  virtual void replay(void);
+
+  /**
+   * Create commands are firends so they can add interfaces to the
+   * handle store.
+   */
+  template <typename MSG>
+  friend class create_cmd;
+
+  /**
+   * Create commands are firends so they can remove interfaces from the
+   * handle store.
+   */
+  template <typename MSG>
+  friend class delete_cmd;
+};
+};
+/*
+ * fd.io coding-style-patch-verification: ON
+ *
+ * Local Variables:
+ * eval: (c-set-style "mozilla")
+ * End:
+ */
+#endif