Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


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 already know how to build and run ONOS locally, write a P4 program, build and run BMv2.


  • Device discovery: connection / disconnection events
  • JSON configuration swap

  • Packet-ins and packet-outs

  • Match-action table population (via flow rule/objective/intent servicerules, flow objectives, or intents)

  • Port statistics collections

  • Flow statistics collection


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's not convenient. The reason is that Instructions in ONOS are modeled after OpenFlow actions (which are protocol-dependent), while flow rule treatments (to be applied as a consequence of a match) are usually defined as a list of multiple instructions. In P4 instead, actions are defined as a compound of low-level protocol-independent primitives (not expressible using ONOS Instructions), and, 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 it's usually program-specific. That’s why we expect a P4 programmer using ONOS to write its own interpretation logic (i.e. Java code) that can map a given treatment instance to a BMv2 action instance.


  • 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 criteria 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 (provided that you write your own P4 program upon as an extension to default.p4) 

Non-standard match and actions


BMv2 extension selectors and treatments can be used to express flow rules with match fields or actions for which either a mapping is not provided by the interpreter, or for which such a mapping is not possible using standard ONOS types. The following code example shows how to create a flow rule that uses these extensions. Header fields and actions can be referenced using the same name used in the P4 program, while the BMv2 configuration is needed by the extension builder to properly format the values according to the specific P4 program (e.g. generate the appropriate byte representation of a given match field).

Code Block
titleCode example of BMv2 extension selectors and treatments
ApplicationId myAppId = ...;
DeviceId myDeviceId = ...'';
Bmv2DeviceContext myContext = ...;

Bmv2Configuration myConfiguration = myContext.configuration();

Ip4Prefix dstPrefix = Ip4Prefix.valueOf("");

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

ExtensionTreatment extTreatment = Bmv2ExtensionTreatment.builder()
        .addParameter("nhop_id", 4)

FlowRule rule = DefaultFlowRule.builder()
                              .extension(extSelector, myDeviceId)
                               .extension(extTreatment, myDeviceId)


Developers guide


ONOS+P4 development environment

To make it easy for you to get started, we prepared a repository with all you need to build and run a Mininet network of BMv2 devices that connect to ONOS. Follow the instructions at this link to get started:

titleExporting environment variables in the shell profile

To get the most from the tools and instructions discussed in the following sections,  it is highly recommended that you add this line to your shell configuration profile (.bash_aliases.profile, etc.):

Code Block
source /<path>/<to>/onos-p4-dev/tools/bash_profile Mininet script

  • Sample commands to run a network of bmv2 devices connected to ONOS
  • Usage with