Application programming
This information describes the programmability features using the control plane services (CPS) infrastructure. Also included is an introduction to basic concepts, YANG data modeling used for programming and the structure of applications, and using template applications and examples.
The CPS infrastructure is at the core of system programmability. The CPS supports the definition of a well-defined, data-centric application programming interface (CPS API) that allows customer applications to interact with system services. System applications also use the CPS API to communicate with one another.
CPS infrastructure provides:
- A distributed framework for application interaction
- Database-like API semantics for create, delete, set, commit, and get operations
- Publish/subscribe semantics
- Object addressability based on object keys
- Introspection
CPS client applications operate on objects and subscribe to events published by CPS server applications. CPS server applications register for the ownership of CPS objects and implement CPS operations, such as object create, set, get, and delete.
A temperature control (TC) application is a simple OPX implementation that shows how the CPS API object model disaggregates client and server applications. The client is the TC application, and the server is the platform adaptation services (PAS) component.
The TC application increases the speed of a system fan when the value reported by a temperature sensor exceeds a pre-defined high threshold — it decreases the fan speed when the temperature falls below another (lower) threshold.
The TC application needs to subscribe to temperature threshold crossing events published by the OPX PAS, and invoke a set request to change the speed of the fan object. Neither the TC application nor the OPX PAS are part of the CPS infrastructure — they function as user applications of the CPS infrastructure.
- Entities handled by the CPS infrastructure are called CPS objects (referred to as objects) — the temperature sensor and the fan are both modeled as objects
- Objects have attributes, for example, temperature value and fan speed
- CPS applications can publish events — when and how events are generated is controlled by the application implementation. For example, an application can publish an event when the value of an attribute changes or when the value of an attribute crosses a threshold.
- CPS applications can subscribe to (listen for) events
- CPS applications can request operations to be performed on objects — a set operation. The CPS service, which registers for the ownership of the specific object category, performs the operation.
- The CPS API provides database-like semantics—services that implement CPS operations (object owners) do not persistently store attribute values
The PAS registers for ownership of both the temperature sensor and fan object types. The PAS application periodically reads the value of a temperature sensor — when the temperature is greater than a pre-defined threshold, the PAS creates an over-temperature event.
The event contains the identity of the temperature sensor object, and possibly the new temperature value. The PAS then publishes the event using one of the CPS API functions. The CPS infrastructure determines the applications that have subscribed for the event and object type, and provides the applications (TC application) with the contents of the event.
The publisher of the event (PAS) does not have any knowledge of the applications that have subscribed for an event, and the subscriber application (TC application) has no knowledge of the application that has published the event.
When the TC application receives the temperature event, it increases the fan speed — it creates a simple CPS transaction in which a set operation requests a change in the speed attribute value of the fan object. CPS API functions perform the transaction. When the transaction is committed, the CPS infrastructure finds the owner of the fan object category — the application that has registered to execute operations requested for fan objects (PAS).
The CPS infrastructure invokes the function registered by PAS to execute the set operation for fans. PAS simply invokes the set operation for low-level fan speed provided by the system device interface (SDI), which acts on the fan hardware and changes its speed.
Entities handled by the CPS infrastructure are called objects. The temperature sensor and the fan are both modeled as objects.
Objects have attributes such as temperature value (sensor object) and fan speed (fan object):
- Applications can publish events — when and how events are generated is controlled by the application implementation. An application can publish an event when the value of an attribute changes, or when the value of an attribute crosses a threshold.
- Applications can subscribe to (listen for) events
- Applications can make requests on objects using a set operation — service which registers for the ownership of the specific object category and performs the operation
- Provides database-like semantics — services that implement operations (object owners) do not necessarily persistently store attribute values.
The concept of a key is central to the CPS infrastructure — all objects require a key. An application uses a key to:
- Register for object events
- Perform get requests
- Perform transactions
A key has two components:
- A fixed key component represented as a sequence (array) of numeric values
- An optional (dynamic) key component
The fixed part of a key consists of:
- Qualifier — Target, observed, real-time
- Attribute identifiers that describe the object name and hierarchy — object category and subcategory. An object category refers to a class of objects, such as interfaces, and object subcategories are defined relative to categories — LAG interface and VLAN interface which are subcategories of interfaces.
| Qualifier | C enum SymbolC enum | String FormSTr | Applicability | Description |
|---|---|---|---|---|
| Target | cps_api_qualifier_TARGET |
target | Configurable attributes | Current running configuration |
| Observed | cps_api_qualifier_OBSERVED |
observed | Configurable attributes and hardware status attributes | Configuration applied to hardware components or current status (provided by monitoring service and can be cached) |
| Realtime | cps_api_qualifier_REALTIME |
realtime | Hardware status attributes and hardware counters | Request values immediately queried from hardware (no caching) |
| Registrations | cps_api_qualifier_REGISTRATION |
objreg | Internal to CPS infrastructure | Qualifier used when publishing events associated to object registrations |
| Proposed | cps_api_qualifier_PROPOSED |
proposed | Not applicable | Reserved |
Keys can be represented in binary form (byte arrays) or string form. Use a string form (name alias) to represent a key in scripting. For example, a numerical representation (entered as a string) of a key is 1.34.2228241.2228246.2228236 — the corresponding name alias is target/base-ip/ipv4/vrf-id/ifindex.
The optional (dynamic) component of a key consists of a series of attribute values stored in the object itself. This key component is created by adding the relevant attributes to the object.
Use the cps_api_key_from_attr_with_qual function to build a CPS key. Create a key by specifying the object name and qualifier:
cps_api_key_from_attr_with_qual(cps_api_object_key(the_object), object_name, cps_api_qualifier_TARGET);
This function looks up the dynamic portion of the key, and copies it into the key using the qualifier target. To add the dynamic portion of the key, add attributes using the standard object attribute function.
CPS objects and object lists are the primitives used in the CPS infrastructure. An object consists of a key (which uniquely identifies the object) and zero or more object attributes.
A CPS object:
- Contains a variable number of attributes
- Can embed other objects
- Can be easily serialized — written to, read from, or a persistent or temporary storage device
- Supports attribute types:
uint8_tuint16_tuint32_tuint64_tchar []
- Attributes that contain other attributes
CPS object attributes are identified by a 64-bit ID tag (attribute identifier) and represented using a type, length, value (TLV) format. The value consists of a sequence of octets.
When an attribute contains a zero-terminated string, the terminating octet must be included in the length field. For example, the total length of the string “Dell” must be set to 5 to include the zero terminating octet.
Although the Python implementation automatically adds a zero octet to all string values, the C/C++ implementation does not. You must take into account the zero-terminating octet when you use a C/C++ application to set the length of an attribute.
A qualifier provides the type of object data to retrieve or act on, and qualifiers are provided as part of the key. The TC example shows a client application specifies the target qualifier in the key of the fan object used to set the fan speed. This qualifier tells the PAS application to apply the specified speed to the fan (hardware) device. Applications can only use the target qualifier for create or set operations.
An application can use any supported qualifier in a get operation:
| Qualifier | Description |
|---|---|
| Target qualifier | Server application (object owner) returns the values of attributes previously specified in a set operation |
| Observed qualifier | Server application (object owner) returns the values of the attributes already successfully applied to hardware entities (for user configurable attributes), or the last retrieved hardware status information values |
| Real-time qualifier | Server application (object owner) reads the current status of the hardware entity to return the value of a requested attribute |
The TC example shows when an application uses the observed qualifier to a get operation on the temperature sensor object — the PAS returns the last value read from the sensor (cached value).
When the real-time qualifier is used, the PAS reads the current value of the sensor and returns the current — instead of the cached value. Using real-time instead of observed qualifiers produces different results when the server application maintains cached values. If the application always reads the current hardware status when it uses a get operation, the results are identical.
When an application retreives an attribute value after a set operation, target and observed qualifiers may produce different results. The TC example shows a set operation to change the fan speed that uses a target qualifier. Because it takes a few seconds for the fan speed to reach the specified value, an immediate get operation using an observed qualifier may return a fan speed value different from a get operation that uses a target qualifier for the fan object key.
The CPS infrastructure provides a subscription mechanism for receiving and publishing object events. An application registers to receive objects using an object key — the key identifies a set of objects in an object category.
An application can register for:
- All events for a given object category
- All events for an object name
When an application publishes an event, subscriber applications receive the event if they have registered a key that has a prefix match with the key associated to the published object.
For example, if you publish a target IPv4 address object that has the base-ip/ipv4/address hierarchy:
- The object key for the object is
{target, base-ip, ipv4, address} - The CPS qualifier (
target) is always a mandatory part of the key - Any application that subscribes for objects that match any keys receives the event:
- Key 1:
{target, base-ip}— receives all events for objects underbase-ip - Key 2:
{target, base-ip,ipv4}— receives all events for objects underipv4 - Key 3:
{target, base-ip,ipv4,address}— receives all IPv4 address objects
- Key 1:
- Multiple applications can subscribe for events that match a specified key
The CPS infrastructure generates events for library-specific conditions, generates events when new object owners (server applications) register with the library, or when objects de-register from the library.
The object key contains the cps_api_qualifier_REGISTRATION qualifier, and the object key for the registration or de-registration event. The key also indicates if the event represents a new object registration or a de-registration.
The CPS infrastructure supports database-like requests to create, update, delete, and retrieve one or more objects in a single operation. The API defines get and transaction functionality, and also defines an action operation to allow applications to perform certain functions without affecting object states.
CPS get requests operate on lists of keys or an object filter that specify the keys of objects to retrieve. An object filter can specify an instance or a range of objects, and block requests that are not within the instance or range of objects. When a get operation completes, the client application receives the list of retrieved objects or an error code if there is a failure.
CPS transactions are required for create, delete and set operations, while the API provides functions to start, commit, and abort transactions. An application must start a transaction, and add operations (create, delete, set or action) and their associated objects to the transaction. A transaction must be committed to complete.
Operations on the objects added to a transaction are not necessarily executed in the order they are specified in the transaction code. The transactions requested by an application thread are always executed in order.
When a transaction is committed, the CPS infrastructure sends all transaction operations to their appropriate handlers, and the result of the request is returned. For a result to be returned, the transaction must be valid and all operations must be received by the registered applications. Transactions allow any create, set or delete operation associated with the transaction to be completed, allowing future CPS calls to use the object data from the commit.
Although it is not necessary for all functions in the transaction to complete, it is necessary that all operations in the transaction are accepted by the registered applications and scheduled for processing. For example, if you add 100,000 routes in a transaction, the result of the commit request is:
- All 100,000 route objects are valid to be created
- Application that creates the route objects completes the request
The transaction commit function returns a success or a failure code. If a transaction commit fails, the entire transaction fails. In this case, the CPS infrastructure automatically calls the rollback functions provided by the CPS server applications. It is the responsibility of the server applications (object-owner applications) to roll back any incremental changes that have already been performed as part of the transaction.
The CPS infrastructure is middleware that facilitates communication between components. The blocking nature of any transaction or its duration is not determined by the CPS infrastructure, but by the implementation of applications registered to use the requested operations (object owners).
The CPS API provides functions for:
- Initialization of the CPS in the context of the calling process
- Key management
- Object handling
- Object attribute handling
- Event handling
- Operations
OPX uses the YANG object model, which is converted to C object-model header files for the CPS object library. Other modeling languages can also be used, provided that a suitable parser and header file generation tool are developed. See YANG object modeling for complete information.
CPS provides C/C++ and Python application programming interfaces.
The transaction commit function returns a success or a failure code — if a transaction commit fails, the entire transaction fails. The CPS infrastructure automatically calls the rollback functions provided by the server applications. It is the responsibility of the server applications (object-owner applications) to rollback any incremental changes that have already been performed as part of the transaction.