FD.io VPP  v18.04-17-g3a0d853
Vector Packet Processing
interface.hpp
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017 Cisco and/or its affiliates.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at:
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef __VOM_INTERFACE_H__
17 #define __VOM_INTERFACE_H__
18 
19 #include "vom/enum_base.hpp"
20 #include "vom/hw.hpp"
21 #include "vom/inspect.hpp"
22 #include "vom/object_base.hpp"
23 #include "vom/om.hpp"
24 #include "vom/prefix.hpp"
25 #include "vom/route_domain.hpp"
26 #include "vom/rpc_cmd.hpp"
27 #include "vom/singular_db.hpp"
28 
29 namespace VOM {
30 /**
31  * Forward declaration of the stats and events command
32  */
33 namespace interface_cmds {
34 class stats_enable_cmd;
35 class events_cmd;
36 };
37 
38 /**
39  * A representation of an interface in VPP
40  */
41 class interface : public object_base
42 {
43 public:
44  struct stats_type_t : public enum_base<stats_type_t>
45  {
46  const static stats_type_t DETAILED;
47  const static stats_type_t NORMAL;
48 
49  private:
50  stats_type_t(int v, const std::string& s);
51  };
52 
53  /**
54  * The key for interface's key
55  */
56  typedef std::string key_t;
57 
58  /**
59  * The iterator type
60  */
63 
64  /**
65  * An interface type
66  */
67  struct type_t : enum_base<type_t>
68  {
69  /**
70  * Unkown type
71  */
72  const static type_t UNKNOWN;
73  /**
74  * A brideged Virtual interface (aka SVI or IRB)
75  */
76  const static type_t BVI;
77  /**
78  * VXLAN interface
79  */
80  const static type_t VXLAN;
81  /**
82  * Ethernet interface type
83  */
84  const static type_t ETHERNET;
85  /**
86  * AF-Packet interface type
87  */
88  const static type_t AFPACKET;
89  /**
90  * loopback interface type
91  */
92  const static type_t LOOPBACK;
93  /**
94  * Local interface type (specific to VPP)
95  */
96  const static type_t LOCAL;
97  /**
98  * TAP interface type
99  */
100  const static type_t TAP;
101 
102  /**
103  * vhost-user interface type
104  */
105  const static type_t VHOST;
106 
107  /**
108  * bond interface type
109  */
110  const static type_t BOND;
111 
112  /**
113  * Convert VPP's name of the interface to a type
114  */
115  static type_t from_string(const std::string& str);
116 
117  private:
118  /**
119  * Private constructor taking the value and the string name
120  */
121  type_t(int v, const std::string& s);
122  };
123 
124  /**
125  * The admin state of the interface
126  */
127  struct admin_state_t : enum_base<admin_state_t>
128  {
129  /**
130  * Admin DOWN state
131  */
132  const static admin_state_t DOWN;
133  /**
134  * Admin UP state
135  */
136  const static admin_state_t UP;
137 
138  /**
139  * Convert VPP's numerical value to enum type
140  */
141  static admin_state_t from_int(uint8_t val);
142 
143  private:
144  /**
145  * Private constructor taking the value and the string name
146  */
147  admin_state_t(int v, const std::string& s);
148  };
149 
150  /**
151  * The oper state of the interface
152  */
153  struct oper_state_t : enum_base<oper_state_t>
154  {
155  /**
156  * Operational DOWN state
157  */
158  const static oper_state_t DOWN;
159  /**
160  * Operational UP state
161  */
162  const static oper_state_t UP;
163 
164  /**
165  * Convert VPP's numerical value to enum type
166  */
167  static oper_state_t from_int(uint8_t val);
168 
169  private:
170  /**
171  * Private constructor taking the value and the string name
172  */
173  oper_state_t(int v, const std::string& s);
174  };
175 
176  /**
177  * Construct a new object matching the desried state
178  */
179  interface(const std::string& name,
180  type_t type,
182  const std::string& tag = "");
183  /**
184  * Construct a new object matching the desried state mapped
185  * to a specific route_domain
186  */
187  interface(const std::string& name,
188  type_t type,
190  const route_domain& rd,
191  const std::string& tag = "");
192  /**
193  * Destructor
194  */
195  virtual ~interface();
196 
197  /**
198  * Copy Constructor
199  */
200  interface(const interface& o);
201 
202  static const_iterator_t cbegin();
203  static const_iterator_t cend();
204 
205  /**
206  * Return the matching'singular' of the interface
207  */
208  std::shared_ptr<interface> singular() const;
209 
210  /**
211  * convert to string format for debug purposes
212  */
213  virtual std::string to_string(void) const;
214 
215  /**
216  * Return VPP's handle to this object
217  */
218  const handle_t& handle() const;
219 
220  /**
221  * Return the interface type
222  */
223  const type_t& type() const;
224 
225  /**
226  * Return the interface type
227  */
228  const std::string& name() const;
229 
230  /**
231  * Return the interface type
232  */
233  const key_t& key() const;
234 
235  /**
236  * Return the L2 Address
237  */
238  const l2_address_t& l2_address() const;
239 
240  /**
241  * Set the admin state of the interface
242  */
243  void set(const admin_state_t& state);
244 
245  /**
246  * Set the L2 Address
247  */
248  void set(const l2_address_t& addr);
249 
250  /**
251  * Set the operational state of the interface, as reported by VPP
252  */
253  void set(const oper_state_t& state);
254 
255  /**
256  * Set the tag to the interface
257  */
258  void set(const std::string& tag);
259 
260  /**
261  * Comparison operator - only used for UT
262  */
263  virtual bool operator==(const interface& i) const;
264 
265  /**
266  * A base class for interface Create commands
267  */
268  template <typename MSG>
269  class create_cmd : public rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>
270  {
271  public:
272  create_cmd(HW::item<handle_t>& item, const std::string& name)
273  : rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>(item)
274  , m_name(name)
275  {
276  }
277 
278  /**
279  * Destructor
280  */
281  virtual ~create_cmd() = default;
282 
283  /**
284  * Comparison operator - only used for UT
285  */
286  virtual bool operator==(const create_cmd& o) const
287  {
288  return (m_name == o.m_name);
289  }
290 
291  /**
292  * Indicate the succeeded, when the HW Q is disabled.
293  */
294  void succeeded()
295  {
297  interface::add(m_name, this->item());
298  }
299 
300  /**
301  * add the created interface to the DB
302  */
303  void insert_interface() { interface::add(m_name, this->item()); }
304 
305  virtual vapi_error_e operator()(MSG& reply)
306  {
307  int sw_if_index = reply.get_response().get_payload().sw_if_index;
308  int retval = reply.get_response().get_payload().retval;
309 
310  VOM_LOG(log_level_t::DEBUG) << this->to_string() << " " << retval;
311 
312  rc_t rc = rc_t::from_vpp_retval(retval);
313  handle_t handle = handle_t::INVALID;
314 
315  if (rc_t::OK == rc) {
316  handle = sw_if_index;
317  }
318 
319  HW::item<handle_t> res(handle, rc);
320 
321  this->fulfill(res);
322 
323  return (VAPI_OK);
324  }
325 
326  protected:
327  /**
328  * The name of the interface to be created
329  */
330  const std::string& m_name;
331  };
332 
333  /**
334  * Base class for intterface Delete commands
335  */
336  template <typename MSG>
337  class delete_cmd : public rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>
338  {
339  public:
340  delete_cmd(HW::item<handle_t>& item, const std::string& name)
341  : rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>(item)
342  , m_name(name)
343  {
344  }
345 
347  : rpc_cmd<HW::item<handle_t>, HW::item<handle_t>, MSG>(item)
348  , m_name()
349  {
350  }
351 
352  /**
353  * Destructor
354  */
355  virtual ~delete_cmd() = default;
356 
357  /**
358  * Comparison operator - only used for UT
359  */
360  virtual bool operator==(const delete_cmd& o) const
361  {
362  return (this->m_hw_item == o.m_hw_item);
363  }
364 
365  /**
366  * Indicate the succeeded, when the HW Q is disabled.
367  */
368  void succeeded() {}
369 
370  /**
371  * remove the deleted interface from the DB
372  */
373  void remove_interface() { interface::remove(this->item()); }
374 
375  protected:
376  /**
377  * The name of the interface to be created
378  */
379  const std::string m_name;
380  };
381 
382  /**
383  * A class that listens to interface Events
384  */
386  {
387  public:
388  /**
389  * Default Constructor
390  */
391  event_listener();
392 
393  /**
394  * Virtual function called on the listener when the command has data
395  * ready to process
396  */
397  virtual void handle_interface_event(interface_cmds::events_cmd* cmd) = 0;
398 
399  /**
400  * Return the HW::item representing the status
401  */
402  HW::item<bool>& status();
403 
404  protected:
405  /**
406  * The status of the subscription
407  */
409  };
410 
411  /**
412  * A class that listens to interface Stats
413  */
415  {
416  public:
417  /**
418  * Default Constructor
419  */
420  stat_listener();
421 
422  /**
423  * Virtual function called on the listener when the command has data
424  * ready to process
425  */
426  virtual void handle_interface_stat(
428 
429  /**
430  * Return the HW::item representing the status
431  */
432  HW::item<bool>& status();
433 
434  protected:
435  /**
436  * The status of the subscription
437  */
439  };
440 
441  /**
442  * The the singular instance of the interface in the DB by handle
443  */
444  static std::shared_ptr<interface> find(const handle_t& h);
445 
446  /**
447  * The the singular instance of the interface in the DB by key
448  */
449  static std::shared_ptr<interface> find(const key_t& k);
450 
451  /**
452  * Dump all interfaces into the stream provided
453  */
454  static void dump(std::ostream& os);
455 
456  /**
457  * Enable stats for this interface
458  */
459  void enable_stats(stat_listener& el,
460  const stats_type_t& st = stats_type_t::NORMAL);
461 
462 protected:
463  /**
464  * Set the handle of an interface object. Only called by the interface
465  * factory during the populate
466  */
467  void set(const handle_t& handle);
468  friend class interface_factory;
469 
470  /**
471  * The SW interface handle VPP has asigned to the interface
472  */
474 
475  /**
476  * Return the matching 'singular' of the interface
477  */
478  virtual std::shared_ptr<interface> singular_i() const;
479 
480  /**
481  * release/remove an interface form the singular store
482  */
483  void release();
484 
485  /**
486  * Virtual functions to construct an interface create commands.
487  * Overridden in derived classes like the sub_interface
488  */
489  virtual std::queue<cmd*>& mk_create_cmd(std::queue<cmd*>& cmds);
490 
491  /**
492  * Virtual functions to construct an interface delete commands.
493  * Overridden in derived classes like the sub_interface
494  */
495  virtual std::queue<cmd*>& mk_delete_cmd(std::queue<cmd*>& cmds);
496 
497  /**
498  * Sweep/reap the object if still stale
499  */
500  virtual void sweep(void);
501 
502  /**
503  * A map of all interfaces key against the interface's name
504  */
506 
507  /**
508  * Add an interface to the DB keyed on handle
509  */
510  static void add(const key_t& name, const HW::item<handle_t>& item);
511 
512  /**
513  * remove an interface from the DB keyed on handle
514  */
515  static void remove(const HW::item<handle_t>& item);
516 
517 private:
518  /**
519  * Class definition for listeners to OM events
520  */
521  class event_handler : public OM::listener, public inspect::command_handler
522  {
523  public:
524  event_handler();
525  virtual ~event_handler() = default;
526 
527  /**
528  * Handle a populate event
529  */
530  void handle_populate(const client_db::key_t& key);
531 
532  /**
533  * Handle a replay event
534  */
535  void handle_replay();
536 
537  /**
538  * Show the object in the Singular DB
539  */
540  void show(std::ostream& os);
541 
542  /**
543  * Get the sortable Id of the listener
544  */
545  dependency_t order() const;
546  };
547 
548  static event_handler m_evh;
549 
550  /**
551  * enable the interface stats in the singular instance
552  */
553  void enable_stats_i(stat_listener& el, const stats_type_t& st);
554 
555  /**
556  * Commit the acculmulated changes into VPP. i.e. to a 'HW" write.
557  */
558  void update(const interface& obj);
559 
560  /*
561  * return the interface's handle in the singular instance
562  */
563  const handle_t& handle_i() const;
564 
565  /*
566  * It's the OM class that calls singular()
567  */
568  friend class OM;
569 
570  /**
571  * It's the singular_db class that calls replay()
572  */
573  friend class singular_db<key_t, interface>;
574 
575  /**
576  * The interfaces name
577  */
578  const std::string m_name;
579 
580  /**
581  * The interface type. clearly this cannot be changed
582  * once the interface has been created.
583  */
584  const type_t m_type;
585 
586  /**
587  * shared pointer to the routeDoamin the interface is in.
588  * NULL is not mapped - i.e. in the default table
589  */
590  std::shared_ptr<route_domain> m_rd;
591 
592  /**
593  * shared pointer to the stats object for this interface.
594  */
595  std::shared_ptr<interface_cmds::stats_enable_cmd> m_stats;
596 
597  /**
598  * The state of the interface
599  */
600  HW::item<admin_state_t> m_state;
601 
602  /**
603  * HW state of the VPP table mapping
604  */
605  HW::item<route::table_id_t> m_table_id;
606 
607  /**
608  * HW state of the L2 address
609  */
610  HW::item<l2_address_t> m_l2_address;
611 
612  /**
613  * The state of the detailed stats collection
614  */
615  HW::item<stats_type_t> m_stats_type;
616 
617  /**
618  * Operational state of the interface
619  */
620  oper_state_t m_oper;
621 
622  /**
623  * tag of the interface
624  */
625  std::string m_tag;
626 
627  /**
628  * A map of all interfaces keyed against VPP's handle
629  */
630  static std::map<handle_t, std::weak_ptr<interface>> m_hdl_db;
631 
632  /**
633  * replay the object to create it in hardware
634  */
635  virtual void replay(void);
636 
637  /**
638  * Create commands are firends so they can add interfaces to the
639  * handle store.
640  */
641  template <typename MSG>
642  friend class create_cmd;
643 
644  /**
645  * Create commands are firends so they can remove interfaces from the
646  * handle store.
647  */
648  template <typename MSG>
649  friend class delete_cmd;
650 };
651 };
652 /*
653  * fd.io coding-style-patch-verification: ON
654  *
655  * Local Variables:
656  * eval: (c-set-style "mozilla")
657  * End:
658  */
659 #endif
delete_cmd(HW::item< handle_t > &item, const std::string &name)
Definition: interface.hpp:340
HWITEM & m_hw_item
A reference to an object&#39;s HW::item that the command will update.
Definition: rpc_cmd.hpp:135
static const rc_t & from_vpp_retval(int32_t rv)
Get the rc_t from the VPP API value.
Definition: types.cpp:36
#define VOM_LOG(lvl)
Definition: logger.hpp:181
void succeeded()
Indicate the succeeded, when the HW Q is disabled.
Definition: interface.hpp:368
static const type_t AFPACKET
AF-Packet interface type.
Definition: interface.hpp:88
A template base class for all enum types.
Definition: enum_base.hpp:30
void remove_interface()
remove the deleted interface from the DB
Definition: interface.hpp:373
const std::string key_t
In the opflex world each entity is known by a URI which can be converted into a string.
Definition: client_db.hpp:51
static const type_t BOND
bond interface type
Definition: interface.hpp:110
HW::item< handle_t > m_hdl
The SW interface handle VPP has asigned to the interface.
Definition: interface.hpp:473
static const stats_type_t NORMAL
Definition: interface.hpp:47
Definition: hw.hpp:33
static const oper_state_t UP
Operational UP state.
Definition: interface.hpp:162
virtual bool operator==(const delete_cmd &o) const
Comparison operator - only used for UT.
Definition: interface.hpp:360
int i
void succeeded()
Indicate the succeeded, when the HW Q is disabled.
Definition: interface.hpp:294
virtual vapi_error_e operator()(MSG &reply)
call operator used as a callback by VAPI when the reply is available
Definition: interface.hpp:305
Error codes that VPP will return during a HW write.
Definition: types.hpp:90
static const log_level_t DEBUG
Definition: logger.hpp:32
static const stats_type_t DETAILED
Definition: interface.hpp:46
create_cmd(HW::item< handle_t > &item, const std::string &name)
Definition: interface.hpp:272
static const handle_t INVALID
A value of an interface handle_t that means the itf does not exist.
Definition: types.hpp:271
The oper state of the interface.
Definition: interface.hpp:153
Type def of a L2 address as read from VPP.
Definition: types.hpp:342
A route-domain is a VRF.
static singular_db< key_t, interface > m_db
A map of all interfaces key against the interface&#39;s name.
Definition: interface.hpp:505
static const type_t LOCAL
Local interface type (specific to VPP)
Definition: interface.hpp:96
const std::string & m_name
The name of the interface to be created.
Definition: interface.hpp:330
static const type_t ETHERNET
Ethernet interface type.
Definition: interface.hpp:84
HW::item< bool > m_status
The status of the subscription.
Definition: interface.hpp:408
static void remove(const HW::item< handle_t > &item)
remove an interface from the DB keyed on handle
Definition: interface.cpp:481
static const oper_state_t DOWN
Operational DOWN state.
Definition: interface.hpp:158
A class that listens to interface Stats.
Definition: interface.hpp:414
#define v
Definition: acl.c:495
A Database to store the unique &#39;singular&#39; instances of a single object type.
Definition: singular_db.hpp:33
A class that listens to interface Events.
Definition: interface.hpp:385
A base class for all RPC commands to VPP.
Definition: rpc_cmd.hpp:38
static void add(const key_t &name, const HW::item< handle_t > &item)
Add an interface to the DB keyed on handle.
Definition: interface.cpp:471
virtual bool operator==(const create_cmd &o) const
Comparison operator - only used for UT.
Definition: interface.hpp:286
A command class represents our desire to recieve interface events.
The admin state of the interface.
Definition: interface.hpp:127
A representation of an interface in VPP.
Definition: interface.hpp:41
Class definition for listeners to OM events.
Definition: om.hpp:284
inspect command handler Handler
Definition: inspect.hpp:54
std::map< KEY, std::weak_ptr< OBJ > >::const_iterator const_iterator
Iterator.
Definition: singular_db.hpp:45
Base class for intterface Delete commands.
Definition: interface.hpp:337
A type declaration of an interface handle in VPP.
Definition: types.hpp:236
dependency_t
There needs to be a strict order in which object types are read from VPP (at boot time) and replayed ...
Definition: types.hpp:43
static const rc_t OK
The HW write was successfull.
Definition: types.hpp:112
success
Definition: vapi_common.h:27
The interface to writing objects into VPP OM.
Definition: om.hpp:140
vhost_vring_state_t state
Definition: vhost-user.h:82
A base class for all object_base in the VPP object_base-Model.
Definition: object_base.hpp:29
static const type_t UNKNOWN
Unkown type.
Definition: interface.hpp:72
const std::string m_name
The name of the interface to be created.
Definition: interface.hpp:379
A command class represents our desire to recieve interface stats.
An interface type.
Definition: interface.hpp:67
static const type_t VXLAN
VXLAN interface.
Definition: interface.hpp:80
A base class for interface Create commands.
Definition: interface.hpp:269
void insert_interface()
add the created interface to the DB
Definition: interface.hpp:303
The VPP Object Model (VOM) library.
Definition: acl_binding.cpp:19
static const admin_state_t UP
Admin UP state.
Definition: interface.hpp:136
A representation of a method call to VPP.
Definition: cmd.hpp:32
static const type_t BVI
A brideged Virtual interface (aka SVI or IRB)
Definition: interface.hpp:76
HW::item< bool > m_status
The status of the subscription.
Definition: interface.hpp:438
void show(char *chroot_path, int verbose)
Definition: svmtool.c:105
static const admin_state_t DOWN
Admin DOWN state.
Definition: interface.hpp:132
static const type_t TAP
TAP interface type.
Definition: interface.hpp:100
singular_db< const std::string, interface >::const_iterator const_iterator_t
The iterator type.
Definition: interface.hpp:62
vhost_vring_addr_t addr
Definition: vhost-user.h:83
static const type_t LOOPBACK
loopback interface type
Definition: interface.hpp:92
std::string key_t
The key for interface&#39;s key.
Definition: interface.hpp:56
delete_cmd(HW::item< handle_t > &item)
Definition: interface.hpp:346
static const type_t VHOST
vhost-user interface type
Definition: interface.hpp:105
vapi_error_e
Definition: vapi_common.h:25