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

Namespaces
	ACL

	arp_proxy_binding_cmds

	arp_proxy_config_cmds

	bond_group_binding_cmds

	bond_interface_cmds

	bridge_domain_arp_entry_cmds

	bridge_domain_cmds

	bridge_domain_entry_cmds

	dhcp_config_cmds

	gbp_contract_cmds

	gbp_endpoint_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	bond_group_binding
	A representation of bond interface binding. More...

class	bond_interface
	A bond-interface. More...

class	bond_member
	A bond-member. 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...

struct	ethertype_t
	Feature Ethertype. More...

class	event_cmd
	An Event command base class. More...

class	file_handler

class	gbp_contract
	A entry in the ARP termination table of a Bridge Domain. More...

class	gbp_endpoint
	A entry in the ARP termination table of a Bridge Domain. More...

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
	An L3 protocol can be used to construct a prefix that is used to match packets are part of a route. 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
	Types belonging to Routing. 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_ref >	object_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 uint32_t	epg_id_t
	EPG IDs are 32 bit integers. 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::BOND_BINDING, 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 gbp_contract::key_t &key)

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

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_t &	logger ()
	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 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)

template<typename DB >
void	db_dump (const DB &db, std::ostream &os)
	Print each of the objects in the DB into the stream provided. More...

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 ethertype_t &eth)
	Output ostream for ethertype_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.

A set of helper function to iterate over objects in the DB.

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.

These functions are delcared not as DB member functions so that the template instatiation of the DB does not require the definitions of the functions used to be declared.

Typedef Documentation

typedef uint32_t VOM::epg_id_t

EPG IDs are 32 bit integers.

Definition at line 30 of file gbp_endpoint.hpp.

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
BOND_BINDING	bond group binding is after interfaces but before anything else
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.

enum VOM::obj_state_t

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

template<typename DB >

void VOM::db_dump	(	const DB &	db,
		std::ostream &	os
	)

Print each of the objects in the DB into the stream provided.

Definition at line 35 of file singular_db_funcs.hpp.

Here is the caller graph for this function:

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 193 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 242 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 287 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 320 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 357 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 70 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 81 of file vxlan_tunnel.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 100 of file interface_span.cpp.

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

ostream print of a handle_t

Definition at line 108 of file types.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 134 of file arp_proxy_config.cpp.

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

Ostream output for the key.

Definition at line 154 of file l3_binding.cpp.

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

Definition at line 160 of file acl_binding.cpp.

Here is the caller graph for this function:

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

Definition at line 165 of file nat_binding.cpp.

Here is the call graph for this function:

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

Definition at line 179 of file gbp_contract.cpp.

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

Definition at line 180 of file bridge_domain_arp_entry.cpp.

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

Ostream operator for a MAC address.

Definition at line 181 of file types.cpp.

Here is the call graph for this function:

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

Definition at line 128 of file neighbour.cpp.

Here is the call graph for this function:

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

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

Definition at line 210 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 260 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 270 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 275 of file types.cpp.

Here is the call graph for this function:

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

Output ostream for ethertype_t.

Definition at line 296 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 278 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 305 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 348 of file prefix.cpp.

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

Definition at line 296 of file prefix.cpp.

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

Definition at line 335 of file prefix.cpp.

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

Definition at line 366 of file prefix.cpp.

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

Definition at line 218 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 224 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 230 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 22 of file vxlan_tunnel.cpp.

Namespaces

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation