ONOS's northbound API has an extension capability which allows applications to use extended features of devices. The idea is to allow devices to expose non-standard features, and to support them in ONOS without polluting the API with device-specific features.

There are two main sections that can be extended: selectors and treatments.

The implementation of ExtensionInstructions for treatments has been completed, and the implementation of selectors is currently underway.

Driver behaviors

Extensions are not supplied by the core; instead they are brought by the driver for the devices that implements them. Applications are not compiled directly against the extension types. This allows them to be added in a completely dynamic way without the ONOS core needing to have any knowledge of the extensions.

There are two behaviors that need to be implemented by drivers that want to provide extensions. They are ExtensionResolver and ExtensionInterpreter.

The ExtensionResolver behavior is used by applications that want to get a reference to an extension object. Calls to the resolver should return instances of an extension if the driver supports that extension.

The ExtensionInterpreter is used by the ONOS core to map extensions to the actual OF messages that need to be sent to switches. 

These behaviours need to be added to the driver definition of the driver in onos-drivers.xml:

...
<driver name="ovs" extends="default"
        manufacturer="Nicira, Inc\." hwVersion="Open vSwitch" swVersion="2\..*">
    <!-- other behaviors -->
    <behaviour api="org.onosproject.openflow.controller.ExtensionInterpreter"
               impl="org.onosproject.driver.extensions.NiciraExtensionInterpreter" />
    <behaviour api="org.onosproject.net.behaviour.ExtensionResolver"
               impl="org.onosproject.driver.extensions.NiciraExtensionInterpreter" />
</driver>
...

Treatment extensions

Treatment extensions are supported through the ExtensionInstruction class. The DefaultTreatmentBuilder has an extension() method where applications can supply the ExtensionInstructions that they have received from the driver's ExtensionResolver behavior. There is a generic setProperty API on ExtensionInstruction that allows an application to add values that might be needed by the extension.

Selector extensions

Under construction - TBD

Sample application usage

// Get the ExtensionResolver behavior of the driver of the switch we're talking to
Driver driver = driverService.getDriver(deviceId);
DriverHandler handler = new DefaultDriverHandler(new DefaultDriverData(driver, deviceId));
ExtensionResolver resolver = handler.behaviour(ExtensionResolver.class);

// Get an instance of the NICIRA_SET_TUNNEL_DST ExtensionInstruction from the driver
ExtensionInstruction extension = resolver.getExtensionInstruction(
        ExtensionType.ExtensionTypes.NICIRA_SET_TUNNEL_DST.type());

// Set the tunnelDst property of the extension instruction.
try {
    extension.setPropertyValue("tunnelDst", Ip4Address.valueOf(1));
} catch (ExtensionPropertyException e) {
    log.error("Error setting extension property", e);
}
 
// Build a treatment that includes the extension (of course we could add other instructions to this treatment as well)
TrafficTreatment treatment = DefaultTrafficTreatment.builder()
	.extension(extension)
	.build()
 
// Now the treatment can be used in whatever object supports treatments: FlowRules, FlowObjectives or Intents.