VPP VOM

VOM has been deprecated circa VPP 21.01

misc: Deprecate VOM

The VPP Object Model (VOM) library

Available in releases 18.01 or later.

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. As such VOM provides some level of insulation to the changes to the VPP binary API. 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!!