Page History

...

This document will guide you through the necessary steps to program a network of BMv2 (virtual) devices using ONOS. This document assumes you are already familiar with ONOS, P4 and BMv2. In other words, we assume you are already able know how to run ONOS locally, you can write a P4 program and you already know how to , compile it for BMv2, build and run BMv2.

Contributors

...

On the northbound, ONOS provides a new Java API called "BMv2 Device Context Service" that can be used by applications to specify at runtime the JSON configuration of a given BMv2 device. Match-action tables can be populated using existing northbound services APIs such a as flow rule, flow objective on or intents, with native support for non-standard P4 match and actions (via extension selectors and treatments).

On the southbound, ONOS speaks with BMv2 using Thrift. This project has been based on a customized version of the BMv2 “simple_switch” target that, differently from the original one, supports primitives for generating to send packet-ins in events to the controller and receiving to receive and transmit packet-outs. The source code of onos-bmv2 is available here.

...

In order to enforce a given JSON configuration on a given device, applications needs to provide a “BMv2 Device Context”. Device contexts are used to bind together in a Java class a BMv2 JSON Configuration configuration and an “Interpreter” implementation. Interpreters are used by ONOS to “understand” a given P4 program. They provide a mapping between ONOS objects and program-specific P4 objects (e.g. headers, actions, table names, etc.), allowing existing services and apps (e.g. host tracking, LLDP discovery, ARP proxy, reactive forwarding, etc.) to work with virtually any P4 program.

...

While for criteria and tables it is possible to specify a 1-to-1 relationship through a map, for Instructions the same is not possible or at least it wouldn't’ be convenient. The reason is that Instructions in ONOS are modeled after OpenFlow actions (which are protocol-dependent) and treatments (to be applied asconsequence as a consequence of a match) are defined usually defined as list a list of Instructionsinstructions. In P4 instead, actions are defined as a compound of low-level protocol-independent primitives (not expressible using ONOS Instructions), butand, most important, P4 allows to specify only one action per table entry. Extracting the "meaning" of a given treatment instance and mapping it to a P4 action is not straightforward and might be progra-specific, That’s why we expect a programmer a P4 programmer using ONOS to write it’s its own interpretation logic (i.e. Java code) that can map a given treatment instance to a BMv2 action instance.

Some questions you might have regarding interpreters:

.

"Default" context

When devices connect for the first time to ONOS a “default” context is automatically applied, triggering a configuration swap on the device and exposing to the system a default interpreter. Such a context is used to provide a minimum set of data plane capabilities for basic ONOS services and apps to work. The default context is based on a default.json BMv2 configuration, (compiled from default.p4) and default interpreter implementation.

FAQ regarding device contexts and interpreters

• Do I necessarily need to write an interpreter for my P4 program?
  No, interpreters are optional, meaning that a context can be created with an “empty” interpreter. In this case, you can’t expect other ONOS services to work with that given context. When not using an Interpreter or when creating flow rules based on non-standard match or actions, developers can use BMv2 extension treatment and selectors.
• Do I need to provide a mapping for all the headers and actions defined in my P4 program?
  No, you can provide a mapping for only some of them. The general advice is to provide a mapping for those criterions and treatments used by the other ONOS services and applications you need in order to run your applications. Most of the times you can re-use the default interpreter.

"Default" context

...

• the

...

• default interpreter

...

• (provided that you write your own P4 program upon default.p4)

...

Anchor
extensions extensions

Non-standard match and actions

ONOS already provides means for applications to process traffic according to match and actions on non-standard header fields...

ApplicationId myAppId = ...;
DeviceId myDeviceId = ...''
Bmv2DeviceContext myContext = ...;

Bmv2Configuration myConfiguration = myContext.configuration();

Ip4Prefix dstPrefix = Ip4Prefix.valueOf("192.16.184.0/24");

ExtensionSelector extSelector = Bmv2ExtensionSelector.builder()
        .forConfiguration(myConfiguration)
        .matchExact("standard_metadata", "ingress_port", 10)
        .matchLpm("ipv4", "dstAddr", dstPrefix.address().toOctets(), dstPrefix.prefixLength())
        .build();

ExtensionTreatment extTreatment = Bmv2ExtensionTreatment.builder()
        .forConfiguration(myConfiguration)
        .setActionName("next_hop")
        .addParameter("nhop_id", 4)
        .build();

FlowRule rule = DefaultFlowRule.builder()
        .forDevice(myDeviceId)
        .fromApp(myAppId)
        .forTable(0)
        .withSelector(DefaultTrafficSelector.builder()
                              .extension(extSelector, myDeviceId)
                              .build())
        .withTreatment(DefaultTrafficTreatment.builder()
                               .extension(extTreatment, myDeviceId)
                               .build())
        .build();

...