FD.io VPP  v18.01.2-1-g9b554f3
Vector Packet Processing
VOM Namespace Reference

The VPP Object Model (VOM) library. More...

Namespaces

 ACL
 
 arp_proxy_binding_cmds
 
 arp_proxy_config_cmds
 
 bridge_domain_arp_entry_cmds
 
 bridge_domain_cmds
 
 bridge_domain_entry_cmds
 
 dhcp_config_cmds
 
 hw_cmds
 
 interface_cmds
 Forward declaration of the stats and events command.
 
 interface_span_cmds
 
 ip_unnumbered_cmds
 
 l2_binding_cmds
 
 l2_emulation_cmds
 
 l3_binding_cmds
 
 lldp_binding_cmds
 
 lldp_global_cmds
 
 nat_binding_cmds
 
 nat_static_cmds
 
 neighbour_cmds
 
 route
 Types belonging to Routing.
 
 route_domain_cmds
 
 sub_interface_cmds
 
 tap_interface_cmds
 
 vxlan_tunnel_cmds
 

Data Structures

class  arp_proxy_binding
 A representation of LLDP client configuration on an interface. More...
 
class  arp_proxy_config
 A representation of LLDP client configuration on an interface. More...
 
class  bridge_domain
 A base class for all object_base in the VPP object_base-Model. More...
 
class  bridge_domain_arp_entry
 A entry in the ARP termination table of a Bridge Domain. More...
 
class  bridge_domain_entry
 A MAC forwarding entry in the bridge-domain/L2-FIB. More...
 
class  client_db
 A DB storing the objects that each owner/key owns. More...
 
class  cmd
 A representation of a method call to VPP. More...
 
class  connection
 A representation of the connection to VPP. More...
 
class  cout_handler
 
class  dhcp_config
 A representation of DHCP client configuration on an interface. More...
 
struct  direction_t
 Feature Directions. More...
 
class  dump_cmd
 A base class for VPP dump commands. More...
 
class  enum_base
 A template base class for all enum types. More...
 
class  event_cmd
 An Event command base class. More...
 
class  file_handler
 
struct  handle_t
 A type declaration of an interface handle in VPP. More...
 
class  HW
 
class  inspect
 A means to inspect the state VPP has built, in total, and per-client. More...
 
class  interface
 A representation of an interface in VPP. More...
 
class  interface_factory
 
class  interface_ip6_nd
 A representation of L3 configuration on an interface. More...
 
class  interface_span
 A representation of interface span configuration. More...
 
class  ip_unnumbered
 A representation of IP unnumbered configuration on an interface. More...
 
struct  l2_address_t
 Type def of a L2 address as read from VPP. More...
 
class  l2_binding
 A Clas representing the binding of an L2 interface to a bridge-domain and the properties of that binding. More...
 
class  l2_emulation
 A Clas representing the binding of an L2 interface to a bridge-domain and the properties of that binding. More...
 
class  l3_binding
 A representation of L3 configuration on an interface. More...
 
class  l3_proto_t
 Types belonging to Routing. More...
 
class  lldp_binding
 A representation of LLDP client configuration on an interface. More...
 
class  lldp_global
 A representation of LLDP global configuration. More...
 
struct  log_level_t
 
class  log_t
 Ideally we'd use the boost logger but that is not prevelent in many distros. More...
 
struct  mac_address_t
 Type def of a Ethernet address. More...
 
class  nat_binding
 A Class representing the binding of an L2 interface to a bridge-domain and the properties of that binding. More...
 
class  nat_static
 A entry in the ARP termination table of a Bridge Domain. More...
 
class  neighbour
 A entry in the neighbour entry (ARP or IPv6 ND) More...
 
class  nh_proto_t
 A next-hop protocol describes the protocol of a peer to which packets are sent after matching a route. More...
 
class  object_base
 A base class for all object_base in the VPP object_base-Model. More...
 
class  object_ref
 A represenation of a reference to a VPP object. More...
 
class  OM
 The interface to writing objects into VPP OM. More...
 
class  ra_config
 A representation of Router Advertisement configuration. More...
 
class  ra_prefix
 A representation of RA prefix configuration on given interface. More...
 
struct  rc_t
 Error codes that VPP will return during a HW write. More...
 
class  route_domain
 A route-domain is a VRF. More...
 
class  rpc_cmd
 A base class for all RPC commands to VPP. More...
 
class  singular_db
 A Database to store the unique 'singular' instances of a single object type. More...
 
class  sub_interface
 A Sub-interface. More...
 
class  tap_interface
 A tap-interface. More...
 
class  vxlan_tunnel
 A representation of a VXLAN Tunnel in VPP. More...
 

Typedefs

typedef std::set< object_refobject_ref_list
 A convenitent typedef for set of objects owned. More...
 
typedef unsigned int(* get_msg_size_t) (void *)
 A function type def for calculating a message's size. More...
 
typedef interface_ip6_nd< ra_config, vapi::Sw_interface_ip6nd_ra_config > ip6nd_ra_config
 Typedef the ip6nd_ra_config. More...
 
typedef interface_ip6_nd< ra_prefix, vapi::Sw_interface_ip6nd_ra_prefix > ip6nd_ra_prefix
 Typedef the ip6nd_ra_prefix. More...
 

Enumerations

enum  obj_state_t { OBJECT_STATE_NONE = 0, OBJECT_STATE_STALE }
 object state More...
 
enum  dependency_t {
  dependency_t::GLOBAL = 0, dependency_t::INTERFACE, dependency_t::TUNNEL, dependency_t::TABLE,
  dependency_t::ACL, dependency_t::BINDING, dependency_t::ENTRY
}
 There needs to be a strict order in which object types are read from VPP (at boot time) and replayed to VPP (if VPP restarts). More...
 

Functions

std::ostream & operator<< (std::ostream &os, const std::pair< direction_t, interface::key_t > &key)
 
std::ostream & operator<< (std::ostream &os, const arp_proxy_config::key_t &key)
 
std::ostream & operator<< (std::ostream &os, const bridge_domain_arp_entry::key_t &key)
 
std::ostream & operator<< (std::ostream &os, const bridge_domain_entry::key_t &key)
 
std::ostream & operator<< (std::ostream &os, const cmd &cmd)
 Free ostream function to print a command. More...
 
std::ostream & operator<< (std::ostream &os, const interface_span::key_t &key)
 Ostream output for the key. More...
 
std::ostream & operator<< (std::ostream &os, const l3_binding::key_t &key)
 Ostream output for the key. More...
 
log_tlogger ()
 Return a log object into which VPP objects can write. More...
 
static std::string get_filename (const std::string &file)
 
static std::string get_timestamp ()
 
std::ostream & operator<< (std::ostream &os, const nat_binding::key_t &key)
 
std::ostream & operator<< (std::ostream &os, const nat_static::key_t &key)
 
std::ostream & operator<< (std::ostream &os, const neighbour::key_t &key)
 
std::ostream & operator<< (std::ostream &os, const object_base &o)
 ostream print of a VPP Obect More...
 
std::ostream & operator<< (std::ostream &os, const l3_proto_t &l3p)
 Ostream output for l3_proto_t. More...
 
boost::asio::ip::address from_bytes (uint8_t is_ip6, uint8_t *array)
 Convert a VPP byte stinrg into a boost addresss. More...
 
void to_bytes (const boost::asio::ip::address_v6 &addr, uint8_t *array)
 
void to_bytes (const boost::asio::ip::address_v4 &addr, uint8_t *array)
 
void to_bytes (const boost::asio::ip::address &addr, uint8_t *is_ip6, uint8_t *array)
 Convert a boost address into a VPP bytes string. More...
 
uint32_t mask_width (const boost::asio::ip::address &addr)
 Get the prefix mask length of a host route from the boost address. More...
 
std::ostream & operator<< (std::ostream &os, const route::prefix_t &pfx)
 Ostream printer for prefix_t. More...
 
boost::asio::ip::address_v4 operator| (const boost::asio::ip::address_v4 &addr1, const boost::asio::ip::address_v4 &addr2)
 
boost::asio::ip::address_v4 operator& (const boost::asio::ip::address_v4 &addr1, const boost::asio::ip::address_v4 &addr2)
 
boost::asio::ip::address_v4 operator~ (const boost::asio::ip::address_v4 &addr1)
 
boost::asio::ip::address_v6 operator| (const boost::asio::ip::address_v6 &addr1, const boost::asio::ip::address_v6 &addr2)
 
boost::asio::ip::address_v6 operator& (const boost::asio::ip::address_v6 &addr1, const boost::asio::ip::address_v6 &addr2)
 
boost::asio::ip::address_v6 operator~ (const boost::asio::ip::address_v6 &addr1)
 
boost::asio::ip::address operator| (const boost::asio::ip::address &addr1, const boost::asio::ip::address &addr2)
 
boost::asio::ip::address operator& (const boost::asio::ip::address &addr1, const boost::asio::ip::address &addr2)
 
boost::asio::ip::address operator~ (const boost::asio::ip::address &addr1)
 
std::ostream & operator<< (std::ostream &os, const handle_t &h)
 ostream print of a handle_t More...
 
std::ostream & operator<< (std::ostream &os, const mac_address_t &mac)
 Ostream operator for a MAC address. More...
 
std::ostream & operator<< (std::ostream &os, const l2_address_t &l2)
 Ostream operator for a MAC address. More...
 
std::ostream & operator<< (std::ostream &os, const direction_t &dir)
 Output ostream for direction_t. More...
 
std::ostream & operator<< (std::ostream &os, const vxlan_tunnel::endpoint_t &ep)
 Ostream output for a tunnel endpoint. More...
 

Variables

static log_t slog
 
const std::string VXLAN_TUNNEL_NAME = "vxlan-tunnel-itf"
 

Detailed Description

The VPP Object Model (VOM) library.

Before we begin, a glossary of terms:

  • Agent or client: A user mode process that links to and uses the VOM library to programme VPP
  • VPP: A running instance of VPP
  • High Availability (HA): Scenarios where the client and/or VPP restart with minimal service interruption.
  • CReate, Update, Delete (CRUD): An API style where the producer issues notifications to changes to objects

The VOM is a C++ library that models entities in VPP as C++ classes. The relationships between VOM objects and VPP entities is not always 1:1. Some effort has been made to construct a higher level, more abstract API to VPP programming*. The client programming model is simple (or at least I intended it to be..). The client deals in ‘desired’ state, that is, it expresses the objects it wants to exists (in VPP) and the properties that the object should have, i.e**; Interface af1(“my-af-packet-1”, AFPACKET, admin::UP); Then the client ‘writes’ this object into the ‘model’ OM::write(“clients-thing-1”, af1);

“clients-thing-1” is a description of the entity within the client’s domain that ‘owns’ (or has locked or has a reference to) the VOM object. There can be many owners of each VOM object. It will be the last owner’s update that will be programmed in VPP. This model means that the client is not burdened with maintaining which of its objects have created which VOM objects. If the client is itself driven by a CRUD API, then create notifications are implemented as above. Update notifications add two extra statements; OM::mark(“clients-thing-1”); … do writes …. OM::sweep(“clients-thing-1”); These ‘mark’ and ‘sweep’ statements are indications to OM that firstly, indicate that all the objects owned by “clients-thing-1” are now stale, i.e that the client may no longer need them. If one of the subsequent writes should update a stale object, then it is no longer stale. The sweep statement will ‘remove’ all the remaining stale objects. In this model, the client does not need to maintain the mapping of VOM objects to its own objects – it can simply express what it needs now. The delete notification is simply: OM::remove(“clients-thing-1”); Which will remove all the objects in VOM that are owned by “clients-thing-1”. Where ‘remove’ in this sense means unlock and unreference, the VOM object, and VPP state, will only be truly removed once there are no more owners. This is equivalent to a mark & sweep with no intermediate writes.

To provide this client side model the VOM is a stateful library, meaning that for each entity it creates in VPP, VOM maintains its own representation of that object. VOM can therefore be memory hungry. The desired state is expressed by the client, the ‘actual’ state is maintained by VOM. VOM will consolidate the two states when the client writes to the OM and thus issue VPP only the changes required.

The concepts of ownership and statefulness also allow the support for HA scenarios. VPP restart: When VPP restarts, VOM will reconnect and ‘replay’ its state, in dependency order, to VPP. The client does not need to regenerate its desired state. Client restart: when the client restarts, VOM will read/dump the current state of all VPP objects and store them in the OM owned by the special owner “boot”. As the client reprogrammes its desired state, objects will become owned by both the boot process and the client. At the point in time, as determined by the client, all stale state, that owned only by boot, can be purged. Hence the system reaches the correct final state, with no interruption to VPP forwarding.

Basic Design:

Each object in VOM (i.e. an interface, route, bridge-domain, etc) is stored in a per-type object database, with an object-type specific key. This ‘singular’ DB has a value-type of a weak pointer to the object. I use the term ‘singular’ to refer to the instance of the object stored in these databases, to be distinct from the instances the client constructs to represent desired state. The ‘client’ DB maintains the mapping of owner to object. The value type of the client DB is a shared pointer to the singular instance of the owned object. Once all the owners are gone, and all the shared pointers are destroyed, the singular instance is also destroyed.

Each VOM object has some basic behaviour: update: issue to VPP an update to this object’s state. This could include the create sweep: delete the VPP entity – called when the object is destroyed. replay: issue to VPP all the commands needed to re-programme (VPP restart HA scenario) populate: read state from VPP and add it to the OM (client restart HA scenario)

The object code is boiler-plate, in some cases (like the ACLs) even template. The objects are purposefully left as simple, functionality free as possible.

Communication with VPP is through a ‘queue’ of ‘commands’. A command is essentially an object wrapper around a VPP binary API call (although we do use the VAPI C++ bindings too). Commands come in three flavours: RPC: do this; done. DUMP: give me all of these things; here you go EVENT; tell me about these events; here’s one …. Here’s one…. Oh here’s another….. etc.

RPC and DUMP commands are handled synchronously. Therefore on return from OM::write(…) VPP has been issued with the request and responded. EVENTs are asynchronous and will be delivered to the listeners in a different thread – so beware!!

As such VOM provides some level of insulation to the changes to the VPP binary API. some of the type names are shorten for brevity’s sake.

Typedef Documentation

typedef unsigned int(* VOM::get_msg_size_t) (void *)

A function type def for calculating a message's size.

Definition at line 30 of file dump_cmd.hpp.

typedef interface_ip6_nd<ra_config, vapi::Sw_interface_ip6nd_ra_config> VOM::ip6nd_ra_config

Typedef the ip6nd_ra_config.

Definition at line 353 of file interface_ip6_nd.hpp.

typedef interface_ip6_nd<ra_prefix, vapi::Sw_interface_ip6nd_ra_prefix> VOM::ip6nd_ra_prefix

Typedef the ip6nd_ra_prefix.

Definition at line 359 of file interface_ip6_nd.hpp.

typedef std::set<object_ref> VOM::object_ref_list

A convenitent typedef for set of objects owned.

A set of shared pointers. This is how the reference counting of an object in the model it managed. Once all these shared ptr and hence references are gone, the object is deleted and any state in VPP is removed.

Definition at line 32 of file client_db.hpp.

Enumeration Type Documentation

enum VOM::dependency_t
strong

There needs to be a strict order in which object types are read from VPP (at boot time) and replayed to VPP (if VPP restarts).

That ordering is defined in this enum types

Enumerator
GLOBAL 

Global Configuration has no dependency.

INTERFACE 

interfaces are the root of the dependency graph

TUNNEL 

Tunnel or virtual interfaces next.

TABLE 

Tables in which entries are added, e.g bridge/route-domains.

ACL 

ACLs.

BINDING 

Then L2/objects that bind to interfaces, BD, ACLS, etc.

ENTRY 

Entries in Tables.

Definition at line 43 of file types.hpp.

object state

Enumerator
OBJECT_STATE_NONE 
OBJECT_STATE_STALE 

indicates the object is stale.

This flag is set when a new epoch is declared. the flag is cleared when the object is updated in the new epoch. If the flag is still set after convergence is declared then the object is deleted

Definition at line 68 of file object_base.hpp.

Function Documentation

boost::asio::ip::address VOM::from_bytes ( uint8_t  is_ip6,
uint8_t *  bytes 
)

Convert a VPP byte stinrg into a boost addresss.

Definition at line 180 of file prefix.cpp.

+ Here is the caller graph for this function:

static std::string VOM::get_filename ( const std::string &  file)
static

Definition at line 82 of file logger.cpp.

static std::string VOM::get_timestamp ( )
static

Definition at line 113 of file logger.cpp.

+ Here is the caller graph for this function:

log_t & VOM::logger ( )

Return a log object into which VPP objects can write.

Definition at line 39 of file logger.cpp.

+ Here is the caller graph for this function:

uint32_t VOM::mask_width ( const boost::asio::ip::address &  addr)

Get the prefix mask length of a host route from the boost address.

Definition at line 229 of file prefix.cpp.

+ Here is the caller graph for this function:

boost::asio::ip::address_v4 VOM::operator& ( const boost::asio::ip::address_v4 &  addr1,
const boost::asio::ip::address_v4 &  addr2 
)

Definition at line 274 of file prefix.cpp.

boost::asio::ip::address_v6 VOM::operator& ( const boost::asio::ip::address_v6 &  addr1,
const boost::asio::ip::address_v6 &  addr2 
)

Definition at line 307 of file prefix.cpp.

boost::asio::ip::address VOM::operator& ( const boost::asio::ip::address &  addr1,
const boost::asio::ip::address &  addr2 
)

Definition at line 344 of file prefix.cpp.

std::ostream & VOM::operator<< ( std::ostream &  os,
const cmd cmd 
)

Free ostream function to print a command.

Definition at line 23 of file cmd.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const object_base o 
)

ostream print of a VPP Obect

Definition at line 56 of file object_base.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const l3_proto_t l3p 
)

Ostream output for l3_proto_t.

Definition at line 57 of file prefix.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const vxlan_tunnel::endpoint_t ep 
)

Ostream output for a tunnel endpoint.

Definition at line 80 of file vxlan_tunnel.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const handle_t h 
)

ostream print of a handle_t

Definition at line 98 of file types.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const interface_span::key_t key 
)

Ostream output for the key.

Definition at line 99 of file interface_span.cpp.

std::ostream & VOM::operator<< ( std::ostream &  os,
const neighbour::key_t key 
)

Definition at line 127 of file neighbour.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const arp_proxy_config::key_t key 
)

Definition at line 132 of file arp_proxy_config.cpp.

std::ostream & VOM::operator<< ( std::ostream &  os,
const nat_static::key_t key 
)

Definition at line 143 of file nat_static.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const std::pair< direction_t, interface::key_t > &  key 
)

Definition at line 146 of file acl_binding.cpp.

+ Here is the caller graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const l3_binding::key_t key 
)

Ostream output for the key.

Definition at line 153 of file l3_binding.cpp.

std::ostream & VOM::operator<< ( std::ostream &  os,
const nat_binding::key_t key 
)

Definition at line 164 of file nat_binding.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const mac_address_t mac 
)

Ostream operator for a MAC address.

Definition at line 171 of file types.cpp.

+ Here is the call graph for this function:

std::ostream& VOM::operator<< ( std::ostream &  os,
const bridge_domain_arp_entry::key_t key 
)
std::ostream & VOM::operator<< ( std::ostream &  os,
const bridge_domain_entry::key_t key 
)

Definition at line 209 of file bridge_domain_entry.cpp.

std::ostream & VOM::operator<< ( std::ostream &  os,
const l2_address_t l2 
)

Ostream operator for a MAC address.

Definition at line 250 of file types.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const route::prefix_t pfx 
)

Ostream printer for prefix_t.

Definition at line 257 of file prefix.cpp.

+ Here is the call graph for this function:

std::ostream & VOM::operator<< ( std::ostream &  os,
const direction_t dir 
)

Output ostream for direction_t.

Definition at line 265 of file types.cpp.

+ Here is the call graph for this function:

boost::asio::ip::address_v4 VOM::operator| ( const boost::asio::ip::address_v4 &  addr1,
const boost::asio::ip::address_v4 &  addr2 
)

Definition at line 265 of file prefix.cpp.

boost::asio::ip::address_v6 VOM::operator| ( const boost::asio::ip::address_v6 &  addr1,
const boost::asio::ip::address_v6 &  addr2 
)

Definition at line 292 of file prefix.cpp.

boost::asio::ip::address VOM::operator| ( const boost::asio::ip::address &  addr1,
const boost::asio::ip::address &  addr2 
)

Definition at line 335 of file prefix.cpp.

boost::asio::ip::address_v4 VOM::operator~ ( const boost::asio::ip::address_v4 &  addr1)

Definition at line 283 of file prefix.cpp.

boost::asio::ip::address_v6 VOM::operator~ ( const boost::asio::ip::address_v6 &  addr1)

Definition at line 322 of file prefix.cpp.

boost::asio::ip::address VOM::operator~ ( const boost::asio::ip::address &  addr1)

Definition at line 353 of file prefix.cpp.

void VOM::to_bytes ( const boost::asio::ip::address_v6 &  addr,
uint8_t *  array 
)

Definition at line 205 of file prefix.cpp.

+ Here is the caller graph for this function:

void VOM::to_bytes ( const boost::asio::ip::address_v4 &  addr,
uint8_t *  array 
)

Definition at line 211 of file prefix.cpp.

void VOM::to_bytes ( const boost::asio::ip::address &  addr,
uint8_t *  is_ip6,
uint8_t *  array 
)

Convert a boost address into a VPP bytes string.

Definition at line 217 of file prefix.cpp.

+ Here is the call graph for this function:

Variable Documentation

log_t VOM::slog
static

Definition at line 36 of file logger.cpp.

const std::string VOM::VXLAN_TUNNEL_NAME = "vxlan-tunnel-itf"

Definition at line 21 of file vxlan_tunnel.cpp.