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