FD.io VPP  v19.04.4-rc0-5-ge88582fac
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 events_cmd;
35 };
36 class stat_reader;
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  * Unknown 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  /**
99  * TAPv2 interface type
100  */
101  const static type_t TAPV2;
102 
103  /**
104  * vhost-user interface type
105  */
106  const static type_t VHOST;
107 
108  /**
109  * bond interface type
110  */
111  const static type_t BOND;
112 
113  /**
114  * pipe-parent type
115  */
116  const static type_t PIPE;
117 
118  /**
119  * pipe-end type
120  */
121  const static type_t PIPE_END;
122 
123  /**
124  * Convert VPP's name of the interface to a type
125  */
126  static type_t from_string(const std::string& str);
127 
128  private:
129  /**
130  * Private constructor taking the value and the string name
131  */
132  type_t(int v, const std::string& s);
133  };
134 
135  /**
136  * The admin state of the interface
137  */
138  struct admin_state_t : enum_base<admin_state_t>
139  {
140  /**
141  * Admin DOWN state
142  */
143  const static admin_state_t DOWN;
144  /**
145  * Admin UP state
146  */
147  const static admin_state_t UP;
148 
149  /**
150  * Convert VPP's numerical value to enum type
151  */
152  static admin_state_t from_int(uint8_t val);
153 
154  private:
155  /**
156  * Private constructor taking the value and the string name
157  */
158  admin_state_t(int v, const std::string& s);
159  };
160 
161  /**
162  * The oper state of the interface
163  */
164  struct oper_state_t : enum_base<oper_state_t>
165  {
166  /**
167  * Operational DOWN state
168  */
169  const static oper_state_t DOWN;
170  /**
171  * Operational UP state
172  */
173  const static oper_state_t UP;
174 
175  /**
176  * Convert VPP's numerical value to enum type
177  */
178  static oper_state_t from_int(uint8_t val);
179 
180  private:
181  /**
182  * Private constructor taking the value and the string name
183  */
184  oper_state_t(int v, const std::string& s);
185  };
186 
187  /**
188  * stats_t:
189  */
190  struct stats_t
191  {
201  };
202 
203  /**
204  * Construct a new object matching the desried state
205  */
206  interface(const std::string& name,
207  type_t type,
209  const std::string& tag = "");
210  /**
211  * Construct a new object matching the desried state mapped
212  * to a specific route_domain
213  */
214  interface(const std::string& name,
215  type_t type,
217  const route_domain& rd,
218  const std::string& tag = "");
219  /**
220  * Destructor
221  */
222  virtual ~interface();
223 
224  /**
225  * Copy Constructor
226  */
227  interface(const interface& o);
228 
229  static const_iterator_t cbegin();
230  static const_iterator_t cend();
231 
232  /**
233  * Return the matching'singular' of the interface
234  */
235  std::shared_ptr<interface> singular() const;
236 
237  /**
238  * convert to string format for debug purposes
239  */
240  virtual std::string to_string(void) const;
241 
242  /**
243  * Return VPP's handle to this object
244  */
245  const handle_t& handle() const;
246 
247  /**
248  * Return the interface type
249  */
250  const type_t& type() const;
251 
252  /**
253  * Return the interface type
254  */
255  const std::string& name() const;
256 
257  /**
258  * Return the interface type
259  */
260  const key_t& key() const;
261 
262  /**
263  * Return the L2 Address
264  */
265  const l2_address_t& l2_address() const;
266 
267  /**
268  * Set the admin state of the interface
269  *
270  * N.B. All set function change only the attibute of the object on whcih
271  * they act, they do not make changes in VPP
272  */
273  void set(const admin_state_t& state);
274 
275  /**
276  * Set the L2 Address
277  */
278  void set(const l2_address_t& addr);
279 
280  /**
281  * Set the operational state of the interface, as reported by VPP
282  */
283  void set(const oper_state_t& state);
284 
285  /**
286  * Set the tag to the interface
287  */
288  void set(const std::string& tag);
289 
290  /**
291  * Get the interface stats
292  */
293  const stats_t& get_stats(void) const;
294 
295  /**
296  * Comparison operator - only used for UT
297  */
298  virtual bool operator==(const interface& i) const;
299 
300  /**
301  * A base class for interface Create commands
302  */
303  template <typename MSG>
304  class create_cmd : public rpc_cmd<HW::item<handle_t>, MSG>
305  {
306  public:
307  create_cmd(HW::item<handle_t>& item, const std::string& name)
308  : rpc_cmd<HW::item<handle_t>, MSG>(item)
309  , m_name(name)
310  {
311  }
312 
313  /**
314  * Destructor
315  */
316  virtual ~create_cmd() = default;
317 
318  /**
319  * Comparison operator - only used for UT
320  */
321  virtual bool operator==(const create_cmd& o) const
322  {
323  return (m_name == o.m_name);
324  }
325 
326  /**
327  * Indicate the succeeded, when the HW Q is disabled.
328  */
329  void succeeded()
330  {
331  rpc_cmd<HW::item<handle_t>, MSG>::succeeded();
332  interface::add(m_name, this->item());
333  }
334 
335  /**
336  * add the created interface to the DB
337  */
338  void insert_interface() { interface::add(m_name, this->item()); }
339 
340  virtual vapi_error_e operator()(MSG& reply)
341  {
342  int sw_if_index = reply.get_response().get_payload().sw_if_index;
343  int retval = reply.get_response().get_payload().retval;
344 
345  VOM_LOG(log_level_t::DEBUG) << this->to_string() << " res:" << retval
346  << " sw-if-index:" << sw_if_index;
347 
348  rc_t rc = rc_t::from_vpp_retval(retval);
349  handle_t handle = handle_t::INVALID;
350 
351  if (rc_t::OK == rc) {
352  handle = sw_if_index;
353  }
354 
355  this->fulfill(HW::item<handle_t>(handle, rc));
356 
357  return (VAPI_OK);
358  }
359 
360  protected:
361  /**
362  * The name of the interface to be created
363  */
364  const std::string& m_name;
365  };
366 
367  /**
368  * Base class for intterface Delete commands
369  */
370  template <typename MSG>
371  class delete_cmd : public rpc_cmd<HW::item<handle_t>, MSG>
372  {
373  public:
374  delete_cmd(HW::item<handle_t>& item, const std::string& name)
375  : rpc_cmd<HW::item<handle_t>, MSG>(item)
376  , m_name(name)
377  {
378  }
379 
381  : rpc_cmd<HW::item<handle_t>, MSG>(item)
382  , m_name()
383  {
384  }
385 
386  /**
387  * Destructor
388  */
389  virtual ~delete_cmd() = default;
390 
391  /**
392  * Comparison operator - only used for UT
393  */
394  virtual bool operator==(const delete_cmd& o) const
395  {
396  return (this->m_hw_item == o.m_hw_item);
397  }
398 
399  /**
400  * Indicate the succeeded, when the HW Q is disabled.
401  */
402  void succeeded() {}
403 
404  /**
405  * remove the deleted interface from the DB
406  */
407  void remove_interface() { interface::remove(this->item()); }
408 
409  protected:
410  /**
411  * The name of the interface to be created
412  */
413  const std::string m_name;
414  };
415 
416  struct event
417  {
419  : itf(itf)
420  , state(state)
421  {
422  }
423 
424  const interface& itf;
426  };
427 
428  /**
429  * A class that listens to interface Events
430  */
432  {
433  public:
434  /**
435  * Default Constructor
436  */
437  event_listener();
438 
439  /**
440  * Virtual function called on the listener when the command has data
441  * ready to process
442  */
443  virtual void handle_interface_event(std::vector<event> es) = 0;
444 
445  /**
446  * Return the HW::item representing the status
447  */
448  HW::item<bool>& status();
449 
450  protected:
451  /**
452  * The status of the subscription
453  */
455  };
456 
457  /**
458  * A class that listens to interface Stats
459  */
461  {
462  public:
463  /**
464  * Default Constructor
465  */
466  stat_listener();
467 
468  virtual ~stat_listener() = default;
469 
470  /**
471  * Virtual function called on the listener when the command has data
472  * ready to process
473  */
474  virtual void handle_interface_stat(const interface&) = 0;
475 
476  /**
477  * Return the HW::item representing the status
478  */
479  HW::item<bool>& status();
480 
481  protected:
482  /**
483  * The status of the subscription
484  */
486  };
487 
488  /**
489  * The the singular instance of the interface in the DB by handle
490  */
491  static std::shared_ptr<interface> find(const handle_t& h);
492 
493  /**
494  * The the singular instance of the interface in the DB by key
495  */
496  static std::shared_ptr<interface> find(const key_t& k);
497 
498  /**
499  * Dump all interfaces into the stream provided
500  */
501  static void dump(std::ostream& os);
502 
503  /**
504  * Enable stats for this interface
505  */
506  void enable_stats(stat_listener* el,
507  const stats_type_t& st = stats_type_t::NORMAL);
508 
509  /**
510  * Disable stats for this interface
511  */
512  void disable_stats();
513 
514  /**
515  * Enable the reception of events of all interfaces
516  */
517  static void enable_events(interface::event_listener& el);
518 
519  /**
520  * disable the reception of events of all interfaces
521  */
522  static void disable_events();
523 
524 protected:
525  /**
526  * Set the handle of an interface object. Only called by the interface
527  * factory during the populate
528  */
529  void set(const handle_t& handle);
530  friend class interface_factory;
531  friend class pipe;
532  /**
533  * The SW interface handle VPP has asigned to the interface
534  */
536 
537  /**
538  * Return the matching 'singular' of the interface
539  */
540  virtual std::shared_ptr<interface> singular_i() const;
541 
542  /**
543  * release/remove an interface form the singular store
544  */
545  void release();
546 
547  /**
548  * Virtual functions to construct an interface create commands.
549  * Overridden in derived classes like the sub_interface
550  */
551  virtual std::queue<cmd*>& mk_create_cmd(std::queue<cmd*>& cmds);
552 
553  /**
554  * Virtual functions to construct an interface delete commands.
555  * Overridden in derived classes like the sub_interface
556  */
557  virtual std::queue<cmd*>& mk_delete_cmd(std::queue<cmd*>& cmds);
558 
559  /**
560  * Sweep/reap the object if still stale
561  */
562  virtual void sweep(void);
563 
564  /**
565  * A map of all interfaces key against the interface's name
566  */
568 
569  /**
570  * Add an interface to the DB keyed on handle
571  */
572  static void add(const key_t& name, const HW::item<handle_t>& item);
573 
574  /**
575  * remove an interface from the DB keyed on handle
576  */
577  static void remove(const HW::item<handle_t>& item);
578 
579 private:
580  /**
581  * Class definition for listeners to OM events
582  */
584  {
585  public:
586  event_handler();
587  virtual ~event_handler() = default;
588 
589  /**
590  * Handle a populate event
591  */
592  void handle_populate(const client_db::key_t& key);
593 
594  /**
595  * Handle a replay event
596  */
597  void handle_replay();
598 
599  /**
600  * Show the object in the Singular DB
601  */
602  void show(std::ostream& os);
603 
604  /**
605  * Get the sortable Id of the listener
606  */
607  dependency_t order() const;
608  };
609 
610  static event_handler m_evh;
611 
612  /**
613  * friend with stat_reader
614  */
615  friend stat_reader;
616 
617  /**
618  * publish stats
619  */
620  void publish_stats();
621 
622  /**
623  * Set the interface stat
624  */
625  void set(const counter_t& count, const std::string& stat_type);
626 
627  /**
628  * enable the interface stats in the singular instance
629  */
630  void enable_stats_i(stat_listener* el, const stats_type_t& st);
631 
632  /**
633  * disable the interface stats in the singular instance
634  */
635  void disable_stats_i();
636 
637  /**
638  * Commit the acculmulated changes into VPP. i.e. to a 'HW" write.
639  */
640  void update(const interface& obj);
641 
642  /*
643  * return the interface's handle in the singular instance
644  */
645  const handle_t& handle_i() const;
646 
647  /*
648  * It's the OM class that calls singular()
649  */
650  friend class OM;
651 
652  /**
653  * It's the singular_db class that calls replay()
654  */
655  friend class singular_db<key_t, interface>;
656 
657  /**
658  * The interfaces name
659  */
660  const std::string m_name;
661 
662  /**
663  * The interface type. clearly this cannot be changed
664  * once the interface has been created.
665  */
666  const type_t m_type;
667 
668  /**
669  * shared pointer to the routeDoamin the interface is in.
670  * NULL is not mapped - i.e. in the default table
671  */
672  std::shared_ptr<route_domain> m_rd;
673 
674  /**
675  * The state of the interface
676  */
677  HW::item<admin_state_t> m_state;
678 
679  /**
680  * HW state of the VPP table mapping
681  */
682  HW::item<route::table_id_t> m_table_id;
683 
684  /**
685  * HW state of the L2 address
686  */
687  HW::item<l2_address_t> m_l2_address;
688 
689  /**
690  * The state of the detailed stats collection
691  */
692  HW::item<stats_type_t> m_stats_type;
693 
694  /**
695  * Interface stats
696  */
697  stats_t m_stats;
698 
699  /**
700  * reference to stat listener
701  */
702  stat_listener* m_listener;
703 
704  /**
705  * Operational state of the interface
706  */
707  oper_state_t m_oper;
708 
709  /**
710  * tag of the interface
711  */
712  std::string m_tag;
713 
714  /**
715  * A map of all interfaces keyed against VPP's handle
716  */
717  static std::map<handle_t, std::weak_ptr<interface>> m_hdl_db;
718 
719  /**
720  * replay the object to create it in hardware
721  */
722  virtual void replay(void);
723 
724  /**
725  * Create commands are firends so they can add interfaces to the
726  * handle store.
727  */
728  template <typename MSG>
729  friend class create_cmd;
730 
731  /**
732  * Create commands are firends so they can remove interfaces from the
733  * handle store.
734  */
735  template <typename MSG>
736  friend class delete_cmd;
737 
738  static std::shared_ptr<interface_cmds::events_cmd> m_events_cmd;
739 };
740 
741 /**
742  * stream insertion operator for interface stats
743  */
744 std::ostream& operator<<(std::ostream& os, const interface::stats_t& stats);
745 };
746 /*
747  * fd.io coding-style-patch-verification: ON
748  *
749  * Local Variables:
750  * eval: (c-set-style "mozilla")
751  * End:
752  */
753 #endif
u32 sw_if_index
Definition: ipsec_gre.api:37
delete_cmd(HW::item< handle_t > &item, const std::string &name)
Definition: interface.hpp:374
A Pipe interface.
Definition: pipe.hpp:31
static const rc_t & from_vpp_retval(int32_t rv)
Get the rc_t from the VPP API value.
Definition: types.cpp:33
#define VOM_LOG(lvl)
Definition: logger.hpp:181
void succeeded()
Indicate the succeeded, when the HW Q is disabled.
Definition: interface.hpp:402
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:407
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:111
HW::item< handle_t > m_hdl
The SW interface handle VPP has asigned to the interface.
Definition: interface.hpp:535
static const stats_type_t NORMAL
Definition: interface.hpp:47
static void disable_events(perfmon_main_t *pm)
Definition: hw.hpp:34
static const type_t PIPE
pipe-parent type
Definition: interface.hpp:116
static const oper_state_t UP
Operational UP state.
Definition: interface.hpp:173
const interface & itf
Definition: interface.hpp:424
int i
void succeeded()
Indicate the succeeded, when the HW Q is disabled.
Definition: interface.hpp:329
virtual vapi_error_e operator()(MSG &reply)
call operator used as a callback by VAPI when the reply is available
Definition: interface.hpp:340
Error codes that VPP will return during a HW write.
Definition: types.hpp:89
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:307
vhost_vring_addr_t addr
Definition: vhost_user.h:121
static const handle_t INVALID
A value of an interface handle_t that means the itf does not exist.
Definition: types.hpp:268
The oper state of the interface.
Definition: interface.hpp:164
Type def of a L2 address as read from VPP.
Definition: types.hpp:339
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:567
static const type_t LOCAL
Local interface type (specific to VPP)
Definition: interface.hpp:96
vhost_vring_state_t state
Definition: vhost_user.h:120
const std::string & m_name
The name of the interface to be created.
Definition: interface.hpp:364
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:454
static void remove(const HW::item< handle_t > &item)
remove an interface from the DB keyed on handle
Definition: interface.cpp:547
static const oper_state_t DOWN
Operational DOWN state.
Definition: interface.hpp:169
A class that listens to interface Stats.
Definition: interface.hpp:460
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:431
A base class for all RPC commands to VPP.
Definition: rpc_cmd.hpp:40
u8 name[64]
Definition: memclnt.api:152
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:537
static const type_t PIPE_END
pipe-end type
Definition: interface.hpp:121
A command class represents our desire to recieve interface events.
The admin state of the interface.
Definition: interface.hpp:138
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:371
A type declaration of an interface handle in VPP.
Definition: types.hpp:233
void event_handler(void *tls_async)
Definition: tls_async.c:340
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:109
success
Definition: vapi_common.h:27
The interface to writing objects into VPP OM.
Definition: om.hpp:140
A base class for all object_base in the VPP object_base-Model.
Definition: object_base.hpp:29
static const type_t UNKNOWN
Unknown type.
Definition: interface.hpp:72
const std::string m_name
The name of the interface to be created.
Definition: interface.hpp:413
size_t count
Definition: vapi.c:47
An interface type.
Definition: interface.hpp:67
std::ostream & operator<<(std::ostream &os, const std::pair< direction_t, interface::key_t > &key)
virtual bool operator==(const create_cmd &o) const
Comparison operator - only used for UT.
Definition: interface.hpp:321
event(const interface &itf, const interface::oper_state_t &state)
Definition: interface.hpp:418
static const type_t VXLAN
VXLAN interface.
Definition: interface.hpp:80
A base class for interface Create commands.
Definition: interface.hpp:304
void insert_interface()
add the created interface to the DB
Definition: interface.hpp:338
The VPP Object Model (VOM) library.
Definition: acl_binding.cpp:19
Stat reader: single interface to get stats.
Definition: stat_reader.hpp:29
static const admin_state_t UP
Admin UP state.
Definition: interface.hpp:147
virtual bool operator==(const delete_cmd &o) const
Comparison operator - only used for UT.
Definition: interface.hpp:394
static const type_t BVI
A brideged Virtual interface (aka SVI or IRB)
Definition: interface.hpp:76
typedef key
Definition: ipsec.api:244
HW::item< bool > m_status
The status of the subscription.
Definition: interface.hpp:485
void show(char *chroot_path, int verbose)
Definition: svmtool.c:105
static const admin_state_t DOWN
Admin DOWN state.
Definition: interface.hpp:143
singular_db< const std::string, interface >::const_iterator const_iterator_t
The iterator type.
Definition: interface.hpp:62
static const type_t TAPV2
TAPv2 interface type.
Definition: interface.hpp:101
interface::oper_state_t state
Definition: interface.hpp:425
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:380
static const type_t VHOST
vhost-user interface type
Definition: interface.hpp:106
HWITEM & m_hw_item
A reference to an object&#39;s HW::item that the command will update.
Definition: rpc_cmd.hpp:134
vapi_error_e
Definition: vapi_common.h:25