Changes between Version 4 and Version 5 of Internal/OpenFlow/VendorTutorial


Ignore:
Timestamp:
Dec 22, 2012, 10:03:53 PM (12 years ago)
Author:
akoshibe
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • Internal/OpenFlow/VendorTutorial

    v4 v5  
    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 the openflowj implementations of the vendor type message and how 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 the openflowj implementations of the vendor type message and how to use them in Floodlight. We'll mostly use snippets of the Nicira vendor messages, found in org.openflow.vendor.nicira, as examples in this page.
    33
    44== Overview ==
    5 The vendor type message has its own message header and a fully customizable payload.
     5Vendor 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.
    66
    77A 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".
    … …  
    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:
    1010{{{
    11 <-------OpenFlow header-------><---Vendor message header--><----vendor message payload----->
     11<-------OpenFlow header-------><---Vendor message header--><----Vendor message payload----->
    1212[OF ver(1)|OFType(1)|length(2)][Vendor ID(2-8)|dataType(4)][user-defined structures(varied)]
    1313}}}
    14 Where the numbers in the parenthesis denote the field size in Bytes. Vendor messages are identified by !OpenFlow message type (OFType) value of 4.
     14Where the numbers in the parenthesis denote the field size in Bytes. The Vendor message header and payloads, in combination, make up the full payload of the vendor message.
    1515
    1616== In openflowj ==
    1717The base interface and framework needed for defining vendor messages are found in the package org.openflow.protocol.vendor.
    1818
    19 `OFVendorData`, is the Java 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:
     19`OFVendorData` is the Java interface for the full payload. All vendor type messages must implement `OFVendorData`. The vendor message header is typically defined in the class that implements this interface. As an example, the vendor ID and data type are part of `OFNiciraVendorData`, the base class for all Nicira vendor messages:
    2020{{{
    2121public class OFNiciraVendorData implements OFVendorData {
    2222
    2323    public static final int NX_VENDOR_ID = 0x00002320;
     24    /**
     25     * The value of the integer data type
     26     * at the beginning of the vendor data
     27     */
     28    protected int dataType;         
    2429...
    2530}}}
    26 This base class is then typically subclassed to implement the various types of this message. 
     31This base class is extended to implement the Request and Reply message types (OFRoleRequestVendorData and OFRoleReplyVendorData, respectively). 
    2732
    28 The Vendor ID and message classes must be registered before it can properly be parsed. This is a two step process. If we take a look at the method ''initVendorMessages()'' from Floodlight's core controller class `Controller`, we see that the vendor ID is registered first:
     33The Vendor ID and data type are the only requirements in terms of vendor header content. The rest may be structured as needed, such as various message fields, getters and setters, and !ChannelBuffer manipulators, which we'll discuss in the section on [#serial serialization]. 
     34
     35=== Message Registration ===
     36The Vendor ID and message classes must be registered before it can properly be parsed. This is a two step process:
     37 1. Vendor ID registration
     38 2. Message type registration
     39
     40We cn confirm 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) followed by each subclass representing a message type:
    2941{{{
    3042    // Configure openflowj to be able to parse the role request/reply vendor messages.
    3143    // first register the vendor ID
    32         OFBasicVendorId niciraVendorId = new OFBasicVendorId(             
    33                 OFNiciraVendorData.NX_VENDOR_ID, 4);               (1)
     44        OFBasicVendorId niciraVendorId = new OFBasicVendorId(                (1)       
     45                OFNiciraVendorData.NX_VENDOR_ID, 4);               
    3446        OFVendorId.registerVendorId(niciraVendorId);
    35 }}}
    36 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 can see that the Nicira vendor ID is 4B long (an Integer).
    3747
    38 Next is the registration of each subclass representing a message type:
    39 {{{
    4048    // then each data type, starting with reqest
    41         OFBasicVendorDataType roleRequestVendorData =                     
     49        OFBasicVendorDataType roleRequestVendorData =                        (2)
    4250                new OFBasicVendorDataType(
    4351                        OFRoleRequestVendorData.NXT_ROLE_REQUEST,
    … …  
    4654   
    4755   //then the repy
    48         OFBasicVendorDataType roleReplyVendorData =
     56        OFBasicVendorDataType roleReplyVendorData =                          (3)
    4957                new OFBasicVendorDataType(
    5058                        OFRoleReplyVendorData.NXT_ROLE_REPLY,
    5159                        OFRoleReplyVendorData.getInstantiable());
    5260         niciraVendorId.registerVendorDataType(roleReplyVendorData);
     61
    5362}}}
    54 Where NXT_ROLE_REQUEST and NXT_ROLE_REPLY are the request and reply data type values for the two Nicira vendor message types. 
     63Where NXT_ROLE_REQUEST and NXT_ROLE_REPLY are the request and reply data type values for the two Nicira vendor message data types.
    5564
    56 As seen above in the instantiation of the OFBasicVendorDataType, the class implementing the vendor data should be instantiable, so that it can be registered properly. The method getInstantiable() should be available in your message classes for this purpose:
     65Several things to point out here:
     66 * 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).
     67 
     68 * As seen above in (2) and (3), the class implementing the vendor data should be instantiable, so that it can be registered properly. The method getInstantiable() should be available in your message classes for this purpose. 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):
    5769{{{
    5870    protected static Instantiable<OFVendorData> instantiable =
    … …  
    7385A 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.
    7486
    75 Each 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 messages is also required for reading. This value does not count the !OpenFlow header, which is added in by helper methods to produce the full message length. The message length must be correct in order for it to be processed by the !OpenFlow channel pipeline.
     87=== Message Serialization === #serial
     88Each 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 of the messages is also required for reading. This value does not count the !OpenFlow header, which is added in by helper methods to produce the full message length. The message length must be correct in order for it to be processed by the !OpenFlow channel pipeline.
     89
     90The 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 in the same order.
    7691
    7792== In Floodlight ==