--- /dev/null
+/*
+ * 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_OM_H__
+#define __VOM_OM_H__
+
+#include <algorithm>
+#include <memory>
+#include <set>
+
+#include "vom/client_db.hpp"
+#include "vom/hw.hpp"
+
+/**
+
+The VPP Object Model (VOM) library.
+
+Before we begin, a glossary of terms:
+ - Agent or client: A user mode process that links to and uses the VOM library
+ to programme VPP
+ - VPP: A running instance of VPP
+ - High Availability (HA): Scenarios where the client and/or VPP restart with
+ minimal service interruption.
+ - CReate, Update, Delete (CRUD): An API style where the producer issues
+ notifications to changes to objects
+
+The VOM is a C++ library that models entities in VPP as C++ classes. The
+ relationships between VOM objects and VPP entities is not always 1:1. Some
+ effort has been made to construct a higher level, more abstract API to VPP
+ programming*.
+The client programming model is simple (or at least I intended it to be..). The
+client deals in ‘desired’ state, that is, it expresses the objects it wants to
+exists (in VPP) and the properties that the object should have, i.e**;
+ Interface af1(“my-af-packet-1”, AFPACKET, admin::UP);
+Then the client ‘writes’ this object into the ‘model’
+ OM::write(“clients-thing-1”, af1);
+
+“clients-thing-1” is a description of the entity within the client’s domain that
+‘owns’ (or has locked or has a reference to) the VOM object. There can be many
+owners of each VOM object. It will be the last owner’s update that will be
+programmed in VPP. This model means that the client is not burdened with
+maintaining which of its objects have created which VOM objects. If the client
+is itself driven by a CRUD API, then create notifications are implemented as
+ above. Update notifications add two extra statements;
+ OM::mark(“clients-thing-1”);
+ … do writes ….
+ OM::sweep(“clients-thing-1”);
+These ‘mark’ and ‘sweep’ statements are indications to OM that firstly, indicate
+that all the objects owned by “clients-thing-1” are now stale, i.e that the
+client may no longer need them. If one of the subsequent writes should update a
+stale object, then it is no longer stale. The sweep statement will ‘remove’ all
+the remaining stale objects. In this model, the client does not need to maintain
+the mapping of VOM objects to its own objects – it can simply express what it
+needs now.
+The delete notification is simply:
+ OM::remove(“clients-thing-1”);
+Which will remove all the objects in VOM that are owned by “clients-thing-1”.
+Where ‘remove’ in this sense means unlock and unreference, the VOM object, and
+VPP state, will only be truly removed once there are no more owners. This is
+equivalent to a mark & sweep with no intermediate writes.
+
+To provide this client side model the VOM is a stateful library, meaning that
+for each entity it creates in VPP, VOM maintains its own representation of that
+object. VOM can therefore be memory hungry. The desired state is expressed by
+the client, the ‘actual’ state is maintained by VOM. VOM will consolidate the
+two states when the client writes to the OM and thus issue VPP only the changes
+required.
+
+The concepts of ownership and statefulness also allow the support for HA
+scenarios.
+VPP restart: When VPP restarts, VOM will reconnect and ‘replay’ its state, in
+dependency order, to VPP. The client does not need to regenerate its desired
+state.
+Client restart: when the client restarts, VOM will read/dump the current state
+of all VPP objects and store them in the OM owned by the special owner “boot”.
+As the client reprogrammes its desired state, objects will become owned by both
+the boot process and the client. At the point in time, as determined by the
+client, all stale state, that owned only by boot, can be purged. Hence the
+system reaches the correct final state, with no interruption to VPP forwarding.
+
+
+Basic Design:
+
+Each object in VOM (i.e. an interface, route, bridge-domain, etc) is stored in a
+per-type object database, with an object-type specific key. This ‘singular’ DB
+has a value-type of a weak pointer to the object. I use the term ‘singular’ to
+refer to the instance of the object stored in these databases, to be distinct
+from the instances the client constructs to represent desired state.
+The ‘client’ DB maintains the mapping of owner to object. The value type of the
+client DB is a shared pointer to the singular instance of the owned object.
+Once all the owners are gone, and all the shared pointers are destroyed, the
+singular instance is also destroyed.
+
+Each VOM object has some basic behaviour:
+ update: issue to VPP an update to this object’s state. This could include the
+ create
+ sweep: delete the VPP entity – called when the object is destroyed.
+ replay: issue to VPP all the commands needed to re-programme (VPP restart HA
+ scenario)
+ populate: read state from VPP and add it to the OM (client restart HA
+scenario)
+
+The object code is boiler-plate, in some cases (like the ACLs) even template.
+The objects are purposefully left as simple, functionality free as possible.
+
+Communication with VPP is through a ‘queue’ of ‘commands’. A command is
+essentially an object wrapper around a VPP binary API call (although we do use
+the VAPI C++ bindings too). Commands come in three flavours:
+ RPC: do this; done.
+ DUMP: give me all of these things; here you go
+ EVENT; tell me about these events; here’s one …. Here’s one…. Oh here’s
+ another….. etc.
+
+RPC and DUMP commands are handled synchronously. Therefore on return from
+OM::write(…) VPP has been issued with the request and responded. EVENTs are
+asynchronous and will be delivered to the listeners in a different thread – so
+beware!!
+
+* As such VOM provides some level of insulation to the changes to the VPP
+ binary API.
+** some of the type names are shorten for brevity’s sake.
+
+*/
+namespace VOM {
+/**
+ * The interface to writing objects into VPP OM.
+ */
+class OM
+{
+public:
+ /**
+ * A class providing the RAII pattern for mark and sweep
+ */
+ class mark_n_sweep
+ {
+ public:
+ /**
+ * Constructor - will call mark on the key
+ */
+ mark_n_sweep(const client_db::key_t& key);
+
+ /**
+ * Destructor - will call sweep on the key
+ */
+ ~mark_n_sweep();
+
+ private:
+ /**
+ * no copies
+ */
+ mark_n_sweep(const mark_n_sweep& ms) = delete;
+
+ /**
+ * The client whose state we are guarding.
+ */
+ client_db::key_t m_key;
+ };
+
+ /**
+ * Init
+ */
+ static void init();
+
+ /**
+ * populate the OM with state read from HW.
+ */
+ static void populate(const client_db::key_t& key);
+
+ /**
+ * Mark all state owned by this key as stale
+ */
+ static void mark(const client_db::key_t& key);
+
+ /**
+ * Sweep all the key's objects that are stale
+ */
+ static void sweep(const client_db::key_t& key);
+
+ /**
+ * Replay all of the objects to HW.
+ */
+ static void replay(void);
+
+ /**
+ * Make the State in VPP reflect the expressed desired state.
+ * But don't call the HW - use this whilst processing dumped
+ * data from HW
+ */
+ template <typename OBJ>
+ static rc_t commit(const client_db::key_t& key, const OBJ& obj)
+ {
+ rc_t rc = rc_t::OK;
+
+ HW::disable();
+ rc = OM::write(key, obj);
+ HW::enable();
+
+ return (rc);
+ }
+
+ /**
+ * Make the State in VPP reflect the expressed desired state.
+ * After processing all the objects in the queue, in FIFO order,
+ * any remaining state owned by the client_db::key_t is purged.
+ * This is a template function so the object's update() function is
+ * always called with the derived type.
+ */
+ template <typename OBJ>
+ static rc_t write(const client_db::key_t& key, const OBJ& obj)
+ {
+ rc_t rc = rc_t::OK;
+
+ /*
+ * Find the singular instance another owner may have created.
+ * this always returns something.
+ */
+ std::shared_ptr<OBJ> inst = obj.singular();
+
+ /*
+ * Update the existing object with the new desired state
+ */
+ inst->update(obj);
+
+ /*
+ * Find if the object already stored on behalf of this key.
+ * and mark them stale
+ */
+ object_ref_list& objs = m_db->find(key);
+
+ /*
+ * Iterate through this list to find a matchin' object
+ * to the one requested.
+ */
+ auto match_ptr = [inst](const object_ref& oref) {
+ return (inst == oref.obj());
+ };
+ auto it = std::find_if(objs.begin(), objs.end(), match_ptr);
+
+ if (it != objs.end()) {
+ /*
+ * yes, this key already owns this object.
+ */
+ it->clear();
+ } else {
+ /*
+ * Add the singular instance to the owners list
+ */
+ objs.insert(object_ref(inst));
+ }
+
+ return (HW::write());
+ }
+
+ /**
+ * Remove all object in the OM referenced by the key
+ */
+ static void remove(const client_db::key_t& key);
+
+ /**
+ * Print each of the object in the DB into the stream provided
+ */
+ static void dump(const client_db::key_t& key, std::ostream& os);
+
+ /**
+ * Print each of the KEYS
+ */
+ static void dump(std::ostream& os);
+
+ /**
+ * Class definition for listeners to OM events
+ */
+ class listener
+ {
+ public:
+ listener() = default;
+ virtual ~listener() = default;
+
+ /**
+ * Handle a populate event
+ */
+ virtual void handle_populate(const client_db::key_t& key) = 0;
+
+ /**
+ * Handle a replay event
+ */
+ virtual void handle_replay() = 0;
+
+ /**
+ * Get the sortable Id of the listener
+ */
+ virtual dependency_t order() const = 0;
+
+ /**
+ * less than operator for set sorting
+ */
+ bool operator<(const listener& listener) const
+ {
+ return (order() < listener.order());
+ }
+ };
+
+ /**
+ * Register a listener of events
+ */
+ static bool register_listener(listener* listener);
+
+private:
+ /**
+ * Database of object state created for each key
+ */
+ static client_db* m_db;
+
+ /**
+ * Comparator to keep the pointers to listeners in sorted order
+ */
+ struct listener_comparator_t
+ {
+ bool operator()(const listener* l1, const listener* l2) const
+ {
+ return (l1->order() < l2->order());
+ }
+ };
+
+ /**
+ * convenient typedef for the sorted set of listeners
+ */
+ typedef std::multiset<listener*, listener_comparator_t> listener_list;
+
+ /**
+ * The listeners for events
+ */
+ static std::unique_ptr<listener_list> m_listeners;
+};
+}
+
+/*
+ * fd.io coding-style-patch-verification: OFF
+ *
+ * Local Variables:
+ * eval: (c-set-style "mozilla")
+ * End:
+ */
+
+#endif
Code Review / vpp.git / blobdiff