Changes between Version 2 and Version 3 of Internal/OpenFlow/VendorTutorial


Ignore:
Timestamp:
Dec 22, 2012, 5:08:17 AM (12 years ago)
Author:
akoshibe
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • Internal/OpenFlow/VendorTutorial

    v2 v3  
    11= 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.
     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.
    33
    44== Overview ==
    5 The vendor type message has its own header and a fully customizable payload.
     5The vendor type message has its own message header and a fully customizable payload.
    66
    7 A 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".
     7A 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 OUI of the vendor. 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".
    88
    99The 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:
     
    1515
    1616== 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:
     17`OFVendorData`, located in package org.openflow.protocol.vendor, 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:
    1818{{{
    1919public class OFNiciraVendorData implements OFVendorData {
     
    2424This base class can then be subclassed to implement the various types of this message. 
    2525
    26 The 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():
     26The Vendor ID and message classes must be registered before it can properly be parsed. This is a two step process. Using the method initVendorMessages() from Floodlight's core controller class `Controller`, we see that the vendor ID is registered first:
    2727{{{
    28     private void initVendorMessages() {
    29         // Configure openflowj to be able to parse the role request/reply vendor messages.
    30         // first register the vendor ID
     28    // Configure openflowj to be able to parse the role request/reply vendor messages.
     29    // first register the vendor ID
    3130        OFBasicVendorId niciraVendorId = new OFBasicVendorId(             
    3231                OFNiciraVendorData.NX_VENDOR_ID, 4);
    3332        OFVendorId.registerVendorId(niciraVendorId);
    34         // then each data type
     33}}}
     34Vendor IDs may vary in length - we indicate that the Nicira vendor ID is an Integer (4B) when we instantiate the !OFBasicVendorId, Next is the registration of each subclass representing a message type:
     35{{{
     36    // then each data type, starting with reqest
    3537        OFBasicVendorDataType roleRequestVendorData =                     
    3638                new OFBasicVendorDataType(
     
    3840                        OFRoleRequestVendorData.getInstantiable());
    3941        niciraVendorId.registerVendorDataType(roleRequestVendorData);
     42   
     43   //then the repy
    4044        OFBasicVendorDataType roleReplyVendorData =
    4145                new OFBasicVendorDataType(
     
    4347                        OFRoleReplyVendorData.getInstantiable());
    4448         niciraVendorId.registerVendorDataType(roleReplyVendorData);
    45     }
    4649}}}
    47 Where NXT_ROLE_REQUEST and NXT_ROLE_REPLY are the request and reply data types.
     50Where NXT_ROLE_REQUEST and NXT_ROLE_REPLY are the request and reply data type values for the two Nicira vendor message types.
    4851
    49 As seen above in the instantiation of the OFBasicVendorDataType,
    50 the class implementing the vendor data should be instantiable, so that
    51 it can be registered properly by the controller. It seems customary to
    52 provide a method, getInstantiable(), for this purpose. This belongs in
    53 the subclass that defines the actual vendor data payload. The code that
    54 does this may look like this:
     52As seen above in the instantiation of the OFBasicVendorDataType, the class implementing the vendor data should be instantiable, so that it can be registered properly by the controller. The method getInstantiable() should be available in your message class for this purpose, and look like this:
    5553{{{
    5654    protected static Instantiable<OFVendorData> instantiable =
    5755            new Instantiable<OFVendorData>() {
    5856                public OFVendorData instantiate() {
    59                     return new OFExportsReply();
     57                    return new OFRoleRequestVendorData();
    6058                }
    6159            };
     
    6967    }
    7068}}}
    71 The above sample was modified slightly to fit my vendor message, but
    72 was almost taken, word-for-word, from the Nicira vendor messages.
     69A non-registered Vendor message data payload is interpreted simply as a byte array (OFByteArrayVendorData to be precise), and cannot be cast to your message (sub)class(es) for further handling.
    7370
    74 A 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).
    75 
     71Each class implementing OFVendorData has 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 of the messaes is also required for reading. This value does not count the !OpenFlow header, which is added in by helper methods to produce the total message length. The message length must be correct in order for it to be processed by the !OpenFlow channel pipeline.