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)
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).
ApplicationId myAppId = ...; DeviceId myDeviceId = ...''; Bmv2DeviceContext myContext = ...; Bmv2Configuration myConfiguration = myContext.configuration(); Ip4Prefix dstPrefix = Ip4Prefix.valueOf("22.214.171.124/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();
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:
- ONOS fork of BMv2 Sample P4 programs
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.):
bmv2.py Mininet script
- Sample commands to run a network of bmv2 devices connected to ONOS
- Usage with onos.py