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_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 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_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 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.

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

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.