FD.io VPP  v19.08-27-gf4dcae4
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  * Return the admin state
269  */
270  const admin_state_t& admin_state() const;
271 
272  /**
273  * Set the admin state of the interface
274  *
275  * N.B. All set function change only the attibute of the object on whcih
276  * they act, they do not make changes in VPP
277  */
278  void set(const admin_state_t& state);
279 
280  /**
281  * Set the L2 Address
282  */
283  void set(const l2_address_t& addr);
284 
285  /**
286  * Set the operational state of the interface, as reported by VPP
287  */
288  void set(const oper_state_t& state);
289 
290  /**
291  * Set the tag to the interface
292  */
293  void set(const std::string& tag);
294 
295  /**
296  * Get the interface stats
297  */
298  const stats_t& get_stats(void) const;
299 
300  /**
301  * Comparison operator - only used for UT
302  */
303  virtual bool operator==(const interface& i) const;
304 
305  /**
306  * A base class for interface Create commands
307  */
308  template <typename MSG>
309  class create_cmd : public rpc_cmd<HW::item<handle_t>, MSG>
310  {
311  public:
312  create_cmd(HW::item<handle_t>& item, const std::string& name)
313  : rpc_cmd<HW::item<handle_t>, MSG>(item)
314  , m_name(name)
315  {
316  }
317 
318  /**
319  * Destructor
320  */
321  virtual ~create_cmd() = default;
322 
323  /**
324  * Comparison operator - only used for UT
325  */
326  virtual bool operator==(const create_cmd& o) const
327  {
328  return (m_name == o.m_name);
329  }
330 
331  /**
332  * Indicate the succeeded, when the HW Q is disabled.
333  */
334  void succeeded()
335  {
336  rpc_cmd<HW::item<handle_t>, MSG>::succeeded();
337  interface::add(m_name, this->item());
338  }
339 
340  /**
341  * add the created interface to the DB
342  */
343  void insert_interface() { interface::add(m_name, this->item()); }
344 
345  virtual vapi_error_e operator()(MSG& reply)
346  {
347  int sw_if_index = reply.get_response().get_payload().sw_if_index;
348  int retval = reply.get_response().get_payload().retval;
349 
350  VOM_LOG(log_level_t::DEBUG) << this->to_string() << " res:" << retval
351  << " sw-if-index:" << sw_if_index;
352 
353  rc_t rc = rc_t::from_vpp_retval(retval);
354  handle_t handle = handle_t::INVALID;
355 
356  if (rc_t::OK == rc) {
357  handle = sw_if_index;
358  }
359 
360  this->fulfill(HW::item<handle_t>(handle, rc));
361 
362  return (VAPI_OK);
363  }
364 
365  protected:
366  /**
367  * The name of the interface to be created
368  */
369  const std::string& m_name;
370  };
371 
372  /**
373  * Base class for intterface Delete commands
374  */
375  template <typename MSG>
376  class delete_cmd : public rpc_cmd<HW::item<handle_t>, MSG>
377  {
378  public:
379  delete_cmd(HW::item<handle_t>& item, const std::string& name)
380  : rpc_cmd<HW::item<handle_t>, MSG>(item)
381  , m_name(name)
382  {
383  }
384 
386  : rpc_cmd<HW::item<handle_t>, MSG>(item)
387  , m_name()
388  {
389  }
390 
391  /**
392  * Destructor
393  */
394  virtual ~delete_cmd() = default;
395 
396  /**
397  * Comparison operator - only used for UT
398  */
399  virtual bool operator==(const delete_cmd& o) const
400  {
401  return (this->m_hw_item == o.m_hw_item);
402  }
403 
404  /**
405  * Indicate the succeeded, when the HW Q is disabled.
406  */
407  void succeeded() {}
408 
409  /**
410  * remove the deleted interface from the DB
411  */
412  void remove_interface() { interface::remove(this->item()); }
413 
414  protected:
415  /**
416  * The name of the interface to be created
417  */
418  const std::string m_name;
419  };
420 
421  struct event
422  {
424  : itf(itf)
425  , state(state)
426  {
427  }
428 
429  const interface& itf;
431  };
432 
433  /**
434  * A class that listens to interface Events
435  */
437  {
438  public:
439  /**
440  * Default Constructor
441  */
442  event_listener();
443 
444  /**
445  * Virtual function called on the listener when the command has data
446  * ready to process
447  */
448  virtual void handle_interface_event(std::vector<event> es) = 0;
449 
450  /**
451  * Return the HW::item representing the status
452  */
453  HW::item<bool>& status();
454 
455  protected:
456  /**
457  * The status of the subscription
458  */
460  };
461 
462  /**
463  * A class that listens to interface Stats
464  */
466  {
467  public:
468  /**
469  * Default Constructor
470  */
471  stat_listener();
472 
473  virtual ~stat_listener() = default;
474 
475  /**
476  * Virtual function called on the listener when the command has data
477  * ready to process
478  */
479  virtual void handle_interface_stat(const interface&) = 0;
480 
481  /**
482  * Return the HW::item representing the status
483  */
484  HW::item<bool>& status();
485 
486  protected:
487  /**
488  * The status of the subscription
489  */
491  };
492 
493  /**
494  * The the singular instance of the interface in the DB by handle
495  */
496  static std::shared_ptr<interface> find(const handle_t& h);
497 
498  /**
499  * The the singular instance of the interface in the DB by key
500  */
501  static std::shared_ptr<interface> find(const key_t& k);
502 
503  /**
504  * Dump all interfaces into the stream provided
505  */
506  static void dump(std::ostream& os);
507 
508  /**
509  * Enable stats for this interface
510  */
511  void enable_stats(stat_listener* el,
512  const stats_type_t& st = stats_type_t::NORMAL);
513 
514  /**
515  * Disable stats for this interface
516  */
517  void disable_stats();
518 
519  /**
520  * Enable the reception of events of all interfaces
521  */
522  static void enable_events(interface::event_listener& el);
523 
524  /**
525  * disable the reception of events of all interfaces
526  */
527  static void disable_events();
528 
529 protected:
530  /**
531  * Set the handle of an interface object. Only called by the interface
532  * factory during the populate
533  */
534  void set(const handle_t& handle);
535  friend class interface_factory;
536  friend class pipe;
537  /**
538  * The SW interface handle VPP has asigned to the interface
539  */
541 
542  /**
543  * Return the matching 'singular' of the interface
544  */
545  virtual std::shared_ptr<interface> singular_i() const;
546 
547  /**
548  * release/remove an interface form the singular store
549  */
550  void release();
551 
552  /**
553  * Virtual functions to construct an interface create commands.
554  * Overridden in derived classes like the sub_interface
555  */
556  virtual std::queue<cmd*>& mk_create_cmd(std::queue<cmd*>& cmds);
557 
558  /**
559  * Virtual functions to construct an interface delete commands.
560  * Overridden in derived classes like the sub_interface
561  */
562  virtual std::queue<cmd*>& mk_delete_cmd(std::queue<cmd*>& cmds);
563 
564  /**
565  * Sweep/reap the object if still stale
566  */
567  virtual void sweep(void);
568 
569  /**
570  * A map of all interfaces key against the interface's name
571  */
573 
574  /**
575  * Add an interface to the DB keyed on handle
576  */
577  static void add(const key_t& name, const HW::item<handle_t>& item);
578 
579  /**
580  * remove an interface from the DB keyed on handle
581  */
582  static void remove(const HW::item<handle_t>& item);
583 
584 private:
585  /**
586  * Class definition for listeners to OM events
587  */
589  {
590  public:
591  event_handler();
592  virtual ~event_handler() = default;
593 
594  /**
595  * Handle a populate event
596  */
597  void handle_populate(const client_db::key_t& key);
598 
599  /**
600  * Handle a replay event
601  */
602  void handle_replay();
603 
604  /**
605  * Show the object in the Singular DB
606  */
607  void show(std::ostream& os);
608 
609  /**
610  * Get the sortable Id of the listener
611  */
612  dependency_t order() const;
613  };
614 
615  static event_handler m_evh;
616 
617  /**
618  * friend with stat_reader
619  */
620  friend stat_reader;
621 
622  /**
623  * publish stats
624  */
625  void publish_stats();
626 
627  /**
628  * Set the interface stat
629  */
630  void set(const counter_t& count, const std::string& stat_type);
631 
632  /**
633  * enable the interface stats in the singular instance
634  */
635  void enable_stats_i(stat_listener* el, const stats_type_t& st);
636 
637  /**
638  * disable the interface stats in the singular instance
639  */
640  void disable_stats_i();
641 
642  /**
643  * Commit the acculmulated changes into VPP. i.e. to a 'HW" write.
644  */
645  void update(const interface& obj);
646 
647  /*
648  * return the interface's handle in the singular instance
649  */
650  const handle_t& handle_i() const;
651 
652  /*
653  * It's the OM class that calls singular()
654  */
655  friend class OM;
656 
657  /**
658  * It's the singular_db class that calls replay()
659  */
660  friend class singular_db<key_t, interface>;
661 
662  /**
663  * The interfaces name
664  */
665  const std::string m_name;
666 
667  /**
668  * The interface type. clearly this cannot be changed
669  * once the interface has been created.
670  */
671  const type_t m_type;
672 
673  /**
674  * shared pointer to the routeDoamin the interface is in.
675  * NULL is not mapped - i.e. in the default table
676  */
677  std::shared_ptr<route_domain> m_rd;
678 
679  /**
680  * The state of the interface
681  */
682  HW::item<admin_state_t> m_state;
683 
684  /**
685  * HW state of the VPP table mapping
686  */
687  HW::item<route::table_id_t> m_table_id;
688 
689  /**
690  * HW state of the L2 address
691  */
692  HW::item<l2_address_t> m_l2_address;
693 
694  /**
695  * The state of the detailed stats collection
696  */
697  HW::item<stats_type_t> m_stats_type;
698 
699  /**
700  * Interface stats
701  */
702  stats_t m_stats;
703 
704  /**
705  * reference to stat listener
706  */
707  stat_listener* m_listener;
708 
709  /**
710  * Operational state of the interface
711  */
712  oper_state_t m_oper;
713 
714  /**
715  * tag of the interface
716  */
717  std::string m_tag;
718 
719  /**
720  * A map of all interfaces keyed against VPP's handle
721  */
722  static std::map<handle_t, std::weak_ptr<interface>> m_hdl_db;
723 
724  /**
725  * replay the object to create it in hardware
726  */
727  virtual void replay(void);
728 
729  /**
730  * Create commands are firends so they can add interfaces to the
731  * handle store.
732  */
733  template <typename MSG>
734  friend class create_cmd;
735 
736  /**
737  * Create commands are firends so they can remove interfaces from the
738  * handle store.
739  */
740  template <typename MSG>
741  friend class delete_cmd;
742 
743  static std::shared_ptr<interface_cmds::events_cmd> m_events_cmd;
744 };
745 
746 /**
747  * stream insertion operator for interface stats
748  */
749 std::ostream& operator<<(std::ostream& os, const interface::stats_t& stats);
750 };
751 /*
752  * fd.io coding-style-patch-verification: ON
753  *
754  * Local Variables:
755  * eval: (c-set-style "mozilla")
756  * End:
757  */
758 #endif
delete_cmd(HW::item< handle_t > &item, const std::string &name)
Definition: interface.hpp:379
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:407
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:412
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:540
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
virtual bool operator==(const delete_cmd &o) const
Comparison operator - only used for UT.
Definition: interface.hpp:399
const interface & itf
Definition: interface.hpp:429
int i
void succeeded()
Indicate the succeeded, when the HW Q is disabled.
Definition: interface.hpp:334
virtual vapi_error_e operator()(MSG &reply)
call operator used as a callback by VAPI when the reply is available
Definition: interface.hpp:345
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:312
vhost_vring_addr_t addr
Definition: vhost_user.h:147
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.
vl_api_interface_index_t sw_if_index
Definition: gre.api:50
static singular_db< key_t, interface > m_db
A map of all interfaces key against the interface&#39;s name.
Definition: interface.hpp:572
static const type_t LOCAL
Local interface type (specific to VPP)
Definition: interface.hpp:96
vhost_vring_state_t state
Definition: vhost_user.h:146
const std::string & m_name
The name of the interface to be created.
Definition: interface.hpp:369
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:459
vl_api_fib_path_type_t type
Definition: fib_types.api:123
static void remove(const HW::item< handle_t > &item)
remove an interface from the DB keyed on handle
Definition: interface.cpp:554
static const oper_state_t DOWN
Operational DOWN state.
Definition: interface.hpp:169
A class that listens to interface Stats.
Definition: interface.hpp:465
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:436
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:544
static const type_t PIPE_END
pipe-end type
Definition: interface.hpp:121
virtual bool operator==(const create_cmd &o) const
Comparison operator - only used for UT.
Definition: interface.hpp:326
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:376
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:418
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)
event(const interface &itf, const interface::oper_state_t &state)
Definition: interface.hpp:423
static const type_t VXLAN
VXLAN interface.
Definition: interface.hpp:80
A base class for interface Create commands.
Definition: interface.hpp:309
void insert_interface()
add the created interface to the DB
Definition: interface.hpp:343
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
static const type_t BVI
A brideged Virtual interface (aka SVI or IRB)
Definition: interface.hpp:76
typedef key
Definition: ipsec.api:245
HW::item< bool > m_status
The status of the subscription.
Definition: interface.hpp:490
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:430
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:385
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