Changes between Initial Version and Version 1 of Internal/OpenFlow/VendorTutorial


Ignore:
Timestamp:
Dec 21, 2012, 10:14:33 PM (12 years ago)
Author:
akoshibe
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • Internal/OpenFlow/VendorTutorial

    v1 v1  
     1= How-To: Extending OpenFlow with Vendor messages =
     2!OpenFlow provides a vendor message type as a way to offer third parties a way to customize the protocol without going out of spec. This tutorial attempts to describe how to create custom vendor messages using openflowj (the Java OpenFlow implementation) and to use them in Floodlight.
     3
     4== Overview ==
     5The vendor type message has its own header and a fully customizable payload.
     6
     7A vendor message must specify a vendor ID and a data type in its header. The vendor ID is a unique ID, typically the OUI, of the vendor implementing the custom message. The data type is used to indicate any subtypes that this message may have. For example, Nicira's vendor messages use Nicira's OUI (002320) as the vendor ID and come in two types, a Request and Reply, indicated by the data types of "10" and "11".
     8
     9The rest of the message is the vendor message payload, and can be freely defined. To sum it up, the full !OpenFlow vendor message takes on the following format:
     10{{{
     11<-------OpenFlow header-------><---Vendor message header--><----vendor message payload----->
     12[OF ver(1)|OFType(1)|length(2)][Vendor ID(2-8)|dataType(4)][user-defined structures(varied)]
     13}}}
     14Where the numbers in the parenthesis denote the field size in Bytes. Vendor messages are identified by !OpenFlow message type (OFType) value of 4.
     15
     16== In openflowj ==
     17`OFVendorData` is the interface for the generic vendor message payload. All vendor type message payloads must implement `OFVendorData`. The vendor ID is also typically defined in the implementing class, as we see here in `OFNiciraVendorData`, the base class for all Nicira vendor messages:
     18{{{
     19public class OFNiciraVendorData implements OFVendorData {
     20
     21    public static final int NX_VENDOR_ID = 0x00002320;
     22...
     23}}}
     24This base class can then be subclassed to implement the various types of this message. 
     25
     26The Vendor ID and VendorData must be registered before it can properly be parsed by your controller. Floodlight's core controller class, `Controller`, registers each vendor message and its subtypes during startup by calling initVendorMessages():
     27{{{
     28    private void initVendorMessages() {
     29        // Configure openflowj to be able to parse the role request/reply
     30        // vendor messages.
     31        OFBasicVendorId niciraVendorId = new OFBasicVendorId(             (1)
     32                OFNiciraVendorData.NX_VENDOR_ID, 4);
     33        OFVendorId.registerVendorId(niciraVendorId);
     34        OFBasicVendorDataType roleRequestVendorData =                     (
     35                new OFBasicVendorDataType(
     36                        OFRoleRequestVendorData.NXT_ROLE_REQUEST,
     37                        OFRoleRequestVendorData.getInstantiable());
     38        niciraVendorId.registerVendorDataType(roleRequestVendorData);
     39        OFBasicVendorDataType roleReplyVendorData =
     40                new OFBasicVendorDataType(
     41                        OFRoleReplyVendorData.NXT_ROLE_REPLY,
     42                        OFRoleReplyVendorData.getInstantiable());
     43         niciraVendorId.registerVendorDataType(roleReplyVendorData);
     44    }
     45}}}
     46
     47{{{
     48   // register vendor ID
     49    OFBasicVendorId ofvid = new OFBasicVendorId(CPL_VENDOR_ID, 4);
     50    OFVendorId.registerVendorId(ofvid);
     51
     52    // and then the message types
     53    OFBasicVendorDataType ofvdt = new OFBasicVendorDataType(20,
     54            OFExportsReply.getInstantiable());
     55    ofvid.registerVendorDataType(ofvdt);
     56}}}
     57
     58A non-registered Vendor message data payload is interpreted simply as a byte array (OFByteArrayVendorData to be precise), and is not easily processed e.g. the methods in your VendorData classes would not be applicable as you would not be able to cast the byte array to your message (sub)class(es).
     59