= How-To: Extending OpenFlow with Vendor messages =
This tutorial attempts to describe how to use the !OpenFlow vendor message to create custom messages. We first provide an overview of the message structure. We then describe the vendor message implementations found in openflowj, the Java implementations of the !OpenFlow protocol used in Floodlight and !FlowVisor. 

We'll mostly use snippets of the Nicira vendor messages, found in org.openflow.vendor.nicira of the Floodlight source, as working examples in this page. The Nicira extensions add !OpenFlow role features, introduced in !OpenFlow v1.2, to the v1.0 protocol used in Floodlight. 

== 1. Overview: The Vendor Message == #intro
!OpenFlow provides a vendor message type as a way to offer third parties a way to customize the protocol without going out of spec. Although called the "Vendor message", this message type provides a handy way for a developer to implement and test out experimental features without wantonly modifying the protocol. 

Vendor messages are identified by !OpenFlow message type (OFType) value of 4. In addition to the standard !OpenFlow header, The vendor type message has its own message header and a fully customizable payload.  

A vendor message header contains a vendor ID and a data type. The vendor ID identifies the vendor implementing the custom message, and is typically the organizationally unique identifier (OUI) of the vendor. As an individual, you can randomly pick and use an integral value for this purpose and nothing would balk at this, but this is highly discouraged. The proper conduct for this case is either to use your institution's OUI (if it has one), or to apply for an ID from the Open Networking Foundation (see [https://www.opennetworking.org/wiki/display/PUBLIC/ONF+Registry here] for details).    

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 comes in two types, a Request and Reply, indicated by the data type values of "10" and "11". 

The 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 general format:
 {{{
    |<------OpenFlow header------>||<----------------------Vendor Data------------------------>|
    |                             ||<-Vendor message header-->||<---Vendor message payload---->|
    [OF ver(1)|OFType(1)|length(2)][Vendor ID(2-8)|dataType(4)][user-defined structures(varied)]
 }}}
Where the numbers in the parenthesis denote the field size in bytes. The vendor message header and payload in combination make up the full payload of the !OpenFlow message, the vendor data.

== 2. In openflowj == #iface
In openflowj, the base interface and framework needed for creating vendor messages are found in the package org.openflow.protocol.vendor. Specifically, openflowj provides developers with a way to define custom vendor data classes.  

`OFVendorData` is the Java interface required by any class defining custom vendor data. `OFVendorData` imposes just a few methods on a class implementing it:
 
 * getLength() : return length of the data
 * readFrom(!ChannelBuffer data, int length) : Read the vendor data from the specified !ChannelBuffer
 * writeTo(!ChannelBuffer data) : Write the vendor data to the specified !ChannelBuffer

These methods are needed for the serialization/deserialization of the message. 

=== 2.1 The Vendor Message Header ===
What we refer to as the "vendor message header" is typically a set of variables defined in the class that implements `OFVendorData`. The class in which these variables are declared typically becomes the base class for further message types. 

For example, the vendor ID and data type are part of `OFNiciraVendorData`, the base class for all Nicira vendor messages:
{{{
public class OFNiciraVendorData implements OFVendorData {

    public static final int NX_VENDOR_ID = 0x00002320;
    /**
     * The value of the integer data type 
     * at the beginning of the vendor data 
     */
    protected int dataType;                          (1)       
...
}}}
`OFNiciraVendorData` is extended to implement the Request and Reply message types (`OFRoleRequestVendorData` and `OFRoleReplyVendorData`, respectively). Note how at (1) the value of dataType is not set within this class - this value is set through the base class's constructor, which takes an integer value for the dataType:
{{{
   /**
     * Contruct Nicira vendor data with the specified data type
     * @param dataType the data type value at the beginning of the vendor data.
     */
    public OFNiciraVendorData(int dataType) {
        this.dataType = dataType;
    }
}}} 
The values passed to this constructor are found in each subclass that represents a message type. We can see this in `OFRoleReplyVendorData`:
{{{
    /**
     * The data type value for a role reply
     */
    public static final int NXT_ROLE_REPLY = 11;     

    /**
     * Construct a role reply vendor data with an unspecified role value.
     */
    public OFRoleReplyVendorData() {
        super(NXT_ROLE_REPLY);               
    }
}}} 
If we trace back, we learn that super() above refers to the constructor of `OFRoleVendorData`, a subclass of `OFNiciraVendorData`. `OFRoleVendorData` takes the value passed to it by `OFRoleReplyVendorData` and passes it to the constructor of its parent class.

This organization isn't a requirement, but makes code reuse easier. The "nesting" of message classes can be thought of as implementing the message structure in layers - Each subclass implements either message components that are encapsulated by components in its parent class, or methods that assign values to variables declared in its super-classes, like in the example above.    

The Vendor ID and data type are the only requirements in terms of vendor header content. Given that the methods required by `OFVendorData` are provided, along with those required for message registration, the message implementation may be structured as needed. The usual additions are various message fields and their getters and setters.  

=== 2.2 Message Registration ===
As expected from the variable structure of vendor messages, a given vendor message must be registered with openflowj before it can handle your messages properly. Registration is a two step process:

 1. Vendor ID registration
 2. Message type registration

We can see this by taking a look at the method ''initVendorMessages()'' from Floodlight's core controller class `Controller`. We see that (1) the vendor ID is registered first, and (2),(3) followed by each class representing a message type:
{{{
    // Configure openflowj to be able to parse the role request/reply vendor messages.
    // first register the vendor ID
        OFBasicVendorId niciraVendorId = new OFBasicVendorId(                (1)       
                OFNiciraVendorData.NX_VENDOR_ID, 4);               
        OFVendorId.registerVendorId(niciraVendorId);

    // then each data type, starting with reqest 
        OFBasicVendorDataType roleRequestVendorData =                        (2)
                new OFBasicVendorDataType(
                        OFRoleRequestVendorData.NXT_ROLE_REQUEST,
                        OFRoleRequestVendorData.getInstantiable());
        niciraVendorId.registerVendorDataType(roleRequestVendorData);
    
   // then the reply
        OFBasicVendorDataType roleReplyVendorData =                          (3)
                new OFBasicVendorDataType(
                        OFRoleReplyVendorData.NXT_ROLE_REPLY,
                        OFRoleReplyVendorData.getInstantiable());
         niciraVendorId.registerVendorDataType(roleReplyVendorData);

}}}
Where, as seen earlier, NXT_ROLE_REQUEST and NXT_ROLE_REPLY are the request and reply data type values for the two Nicira vendor message data types.

There are two things to point out here:
 1. Since vendor IDs may vary in length, we indicate the length in bytes that the vendor ID is when we instantiate the OFBasicVendorId. In (1) we provide the constructor with the value 4 along with the actual Vendor ID, indicating that the Nicira vendor ID is an integer (4 bytes long). 
 
 2. As seen above in (2) and (3), the class implementing vendor data must provide an instantiator. The instantiator provides `OFBasicVendorDataType` with a format that allows it to safely avoid making assumptions about the structure of the vendor data. The method ''getInstantiable()'' returns an instantiator for the class.   

The second point indicates that we need a ''getInstantiable()'' (or something of equal function) in our vendor data class. The following snippet was taken from `OFRoleRequestVendorData`, but the structure will pretty much be the same for any vendor data class (e.g. replace OFRoleRequestVendorData below with your class):
{{{
    protected static Instantiable<OFVendorData> instantiable =
            new Instantiable<OFVendorData>() {
                public OFVendorData instantiate() {
                    return new OFRoleRequestVendorData();
                }
            };

    /**
     * @return a subclass of Instantiable<OFVendorData> that instantiates
     *         an instance of OFRoleRequestVendorData.
     */
    public static Instantiable<OFVendorData> getInstantiable() {
        return instantiable;
    }
}}}
A non-registered Vendor message data payload is interpreted simply as a byte array (an OFByteArrayVendorData object, to be precise), and cannot be cast to your message (sub)class(es) for further handling. Aside from throwing a !ClassCastException if you try, this is inconvenient since you won't be able to invoke the class methods specific to your vendor data class for message-specific processing.  

=== 2.3 Message Serialization === #serial 
As mentioned [#iface earlier], a class implementing OFVendorData must have a readFrom(!ChannelBuffer data, int length) and writeTo(!ChannelBuffer data) method for reading and writing the data from/to a !ChannelBuffer. A getLength() method that returns the size in bytes of the vendor data, minus the Vendor ID length, is also required for properly reading/writing from the !ChannelBuffer. We do not count the !OpenFlow header length since helper methods take it into account along with the Vendor ID length to produce the full message length. 

The packet structure is determined by the order in which the various fields are written to the !ChannelBuffer, so readFrom() and writeTo() should read/write the fields to/from the !ChannelBuffer in the same order. 

As an example, we can look at `OFRoleVendorData`, the parent class of the Nicira Request and Reply messages. Since both messages only differ in the values of the ''role'' field, the readFrom(), writeTo(), and getLength() methods for the final packet structure are defined in this class. The message structure looks like this:
{{{
                     |<-Vendor ID->||<-dataType->|<----payload(4)--->|                             
    [OpenFlow Header][ 0x00002320  ][    10|11   ][      0|1|2       ]
}}} 
Where the values within the square brackets separated by pipes are the various decimal values that the fields can take. For this message, what we had dubbed the vendor message payload in section [#intro 1] is one integral value of 4 bytes, used to indicate controller role. The packet structure is reflected in readFrom() and writeTo():
{{{
    public void readFrom(ChannelBuffer data, int length) {
        super.readFrom(data, length);
        role = data.readInt();
    }

    public void writeTo(ChannelBuffer data) {
        super.writeTo(data);
        data.writeInt(role);
    }
}}}
super in this case is `OFNiciraVendorData`, which takes care of reading and writing the integral dataType field:
{{{
    @Override
    public void readFrom(ChannelBuffer data, int length) {
        dataType = data.readInt();
    }

    @Override
    public void writeTo(ChannelBuffer data) {
        data.writeInt(dataType);
    }
}}}

As for getLength(), the total returned is the length of the two fields (8 bytes). looking at the two classes side-by-side makes this clear. First `OFRoleVendorData`:
{{{
    @Override
    public int getLength() {
        return super.getLength() + 4;
    }
}}}
Then `OFNiciraVendorData`:
{{{
    @Override
    public int getLength() {
        return 4;
    }
}}} 

== 3. The full Vendor Message ==
This section describes how to construct the full vendor type message once we have a structured vendor data object, or alternatively, parse a vendor type message containing a known type of vendor data.  

=== 3.1 Message construction ===
The vendor data is just the payload of an !OpenFlow vendor type message. The !OpenFlow header must be added to the vendor data before it can be sent out on the channel.   

=== 3.2 Reading message contents ===