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