From 812ed39f9da336310e815c361ab5a9f118657d94 Mon Sep 17 00:00:00 2001 From: Neale Ranns Date: Mon, 16 Oct 2017 04:20:13 -0700 Subject: 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 Co-authored-by: Mohsin Kazmi --- src/vpp-api/vom/hw.hpp | 408 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 src/vpp-api/vom/hw.hpp (limited to 'src/vpp-api/vom/hw.hpp') diff --git a/src/vpp-api/vom/hw.hpp b/src/vpp-api/vom/hw.hpp new file mode 100644 index 00000000000..00ab2d647f1 --- /dev/null +++ b/src/vpp-api/vom/hw.hpp @@ -0,0 +1,408 @@ +/* + * 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_HW_H__ +#define __VOM_HW_H__ + +#include +#include +#include +#include +#include + +#include +#include + +#include "vom/connection.hpp" +#include "vom/rpc_cmd.hpp" + +namespace VOM { +class HW +{ +public: + /** + * A HW::item is data that is either to be written to or read from + * VPP/HW. + * The item is a pair of the data written/read and the result of that + * operation. + */ + template + class item + { + public: + /** + * Constructor + */ + item(const T& data) + : item_data(data) + , item_rc(rc_t::NOOP) + { + } + /** + * Constructor + */ + item() + : item_rc(rc_t::UNSET) + { + } + + /** + * Constructor + */ + item(rc_t rc) + : item_rc(rc) + { + } + + /** + * Constructor + */ + item(const T& data, rc_t rc) + : item_data(data) + , item_rc(rc) + { + } + + /** + * Comparison operator + */ + bool operator==(const item& i) const + { + return (item_data == i.item_data); + } + + /** + * Copy assignment + */ + item& operator=(const item& other) + { + item_data = other.item_data; + item_rc = other.item_rc; + + return (*this); + } + + /** + * Return the data read/written + */ + T& data() { return (item_data); } + + /** + * Const reference to the data + */ + const T& data() const { return (item_data); } + + /** + * Get the HW return code + */ + rc_t rc() const { return (item_rc); } + + /** + * Set the HW return code - should only be called from the + * family of Command objects + */ + void set(const rc_t& rc) { item_rc = rc; } + + /** + * Return true if the HW item is configred in HW + */ + operator bool() const { return (rc_t::OK == item_rc); } + + /** + * update the item to the desired state. + * return true if a HW update is required + */ + bool update(const item& desired) + { + bool need_hw_update = false; + + /* + * if the deisred set is unset (i.e. defaulted, we've + * no update to make + */ + if (rc_t::UNSET == desired.rc()) { + return (false); + } + /* + * A HW update is needed if thestate is different + * or the state is not yet in HW + */ + need_hw_update = (item_data != desired.data() || rc_t::OK != rc()); + + item_data = desired.data(); + + return (need_hw_update); + } + + /** + * convert to string format for debug purposes + */ + std::string to_string() const + { + std::ostringstream os; + + os << "hw-item:[" + << "rc:" << item_rc.to_string() << " data:" << item_data.to_string() + << "]"; + + return (os.str()); + } + + private: + /** + * The data + */ + T item_data; + + /** + * The result when the item was written + */ + rc_t item_rc; + }; + + /** + * The pipe to VPP into which we write the commands + */ + class cmd_q + { + public: + /** + * Constructor + */ + cmd_q(); + /** + * Destructor + */ + ~cmd_q(); + + /** + * Copy assignement - only used in UT + */ + cmd_q& operator=(const cmd_q& f); + + /** + * Enqueue a command into the Q. + */ + virtual void enqueue(cmd* c); + /** + * Enqueue a command into the Q. + */ + virtual void enqueue(std::shared_ptr c); + + /** + * Enqueue a set of commands + */ + virtual void enqueue(std::queue& c); + + /** + * dequeue a command from the Q. + */ + virtual void dequeue(cmd* c); + + /** + * dequeue a command from the Q. + */ + virtual void dequeue(std::shared_ptr c); + + /** + * Write all the commands to HW + */ + virtual rc_t write(); + + /** + * Blocking Connect to VPP - call once at bootup + */ + void connect(); + + /** + * Disable the passing of commands to VPP. Whilst disabled all + * writes will be discarded. Use this during the reset phase. + */ + void disable(); + + /** + * Enable the passing of commands to VPP - undoes the disable. + * The Q is enabled by default. + */ + void enable(); + + private: + /** + * A queue of enqueued commands, ready to be written + */ + std::deque> m_queue; + + /** + * A map of issued, but uncompleted, commands. + * i.e. those that we are waiting, async stylee, + * for VPP to complete + */ + std::map> m_pending; + + /** + * VPP Q poll function + */ + void rx_run(); + + /** + * The thread object running the poll/dispatch/connect thread + */ + std::unique_ptr m_rx_thread; + + /** + * A flag indicating the client has disabled the cmd Q. + */ + bool m_enabled; + + /** + * A flag for the thread to poll to see if the queue is still alive + */ + bool m_connected; + + /** + * The connection to VPP + */ + connection m_conn; + }; + + /** + * Initialise the HW connection to VPP - the UT version passing + * a mock Q. + */ + static void init(cmd_q* f); + + /** + * Initialise the HW + */ + static void init(); + + /** + * Enqueue A command for execution + */ + static void enqueue(cmd* f); + + /** + * Enqueue A command for execution + */ + static void enqueue(std::shared_ptr c); + + /** + * Enqueue A set of commands for execution + */ + static void enqueue(std::queue& c); + + /** + * dequeue A command for execution + */ + static void dequeue(cmd* f); + + /** + * dequeue A command for execution + */ + static void dequeue(std::shared_ptr c); + + /** + * Write/Execute all commands hitherto enqueued. + */ + static rc_t write(); + + /** + * Blocking Connect to VPP + */ + static void connect(); + + /** + * Blocking pool of the HW connection + */ + static bool poll(); + +private: + /** + * The command Q toward HW + */ + static cmd_q* m_cmdQ; + + /** + * HW::item representing the connection state as determined by polling + */ + static HW::item m_poll_state; + + /** + * Disable the passing of commands to VPP. Whilst disabled all writes + * will be discarded. Use this during the reset phase. + */ + static void disable(); + + /** + * Enable the passing of commands to VPP - undoes the disable. + * The Q is enabled by default. + */ + static void enable(); + + /** + * Only the OM can enable/disable HW + */ + friend class OM; + + /** + * A command pool the HW for liveness + */ + class Poll : public rpc_cmd, rc_t, vapi::Control_ping> + { + public: + /** + * Constructor taking the HW::item to update + */ + Poll(HW::item& item); + + /** + * 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 Poll& i) const; + }; +}; + +/** + * bool Specialisation for HW::item to_string + */ +template <> +std::string HW::item::to_string() const; + +/** + * uint Specialisation for HW::item to_string + */ +template <> +std::string HW::item::to_string() const; +}; + +/* + * fd.io coding-style-patch-verification: ON + * + * Local Variables: + * eval: (c-set-style "mozilla") + * End: + */ + +#endif -- cgit 1.2.3-korg