Changes between Version 9 and Version 10 of Internal/OpenFlow/VendorTutorial

Timestamp:

Jan 4, 2013, 11:46:33 PM (12 years ago)

Author:

akoshibe

Comment:

—

Internal/OpenFlow/VendorTutorial

@@ -21 +21 @@
 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.  
-
+== 2. 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. We start with a brief overview of the interface provided for this purpose and the general approach used for vendor data implementation, after which we describe the detailed requirements for implementing vendor data.   
+
+==== Interface OFVendorData ====
 `OFVendorData` is the Java interface required by any class defining custom vendor data. `OFVendorData` imposes just a few methods on a class implementing it:
  
@@ -32 +33 @@
 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. 
+==== Structuring the code ====
+A custom vendor message is comprised of the !OpenFlow header that identifies it as a vendor type message, and the vendor data. The vendor data is usually implemented as a collection of classes - one base class that implements `OFVendorData` and defines the Vendor ID, and the various subclasses that extend the base class to implement the individual message types.    
+
+This organization isn't a requirement, but makes code reuse easier. The "nesting" of message classes can be thought of as the implementation of the message structure in layers - Each subclass implements either 1) message components that are encapsulated by components in its parent class, and/or 2) methods that assign values to variables declared in its super-classes. We will see the this in the code snippets to follow. 
+
+=== 2.1 The Nicira vendor messages ===
+As mentioned earlier, the Nicira vendor messages implement newer protocol features in an older version of !OpenFlow that does not support it. This vendor message's two message types are implemented across four classes with the following parent-child relations:
+{{{
+                                                              
+    OFNiciraVendorData--->OFRoleVendorData--+--->OFRoleRequestVendorData
+                                            | 
+    ---> = "parent class of"                +--->OFRoleReplyVendorData
+
+}}} 
+Where `OFNiciraVendorData` is the base class implementing `OFVendorData`, and `OFRoleRequestVendorData` and `OFRoleReplyVendorData` implement the two message types. This chart will hopefully make more sense with the following sections. 
+
+=== 2.1 Vendor Data Components ===
+What we refer to as the "vendor message header" is typically a set of variables defined in the class that implements `OFVendorData`. 
 
 For example, the vendor ID and data type are part of `OFNiciraVendorData`, the base class for all Nicira vendor messages:
@@ -47 +64 @@
 ...
 }}}
-`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:
+As explained in the start of the section, `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:
 {{{
    /**
@@ -73 +90 @@
 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.  
+You may wonder what the purpose of `OFRoleVendorData` is - for now, it is okay to think of it as the class that defines the single-integer vendor data payload common to both Request and Reply message types, and the values that it can take ("role values" as commented below): 
+{{{
+    public class OFRoleVendorData extends OFNiciraVendorData {
+    
+        /**
+         * Role value indicating that the controller is in the OTHER role.
+         */
+        public static final int NX_ROLE_OTHER = 0;
+    
+        /**
+         * Role value indicating that the controller is in the MASTER role.
+         */
+        public static final int NX_ROLE_MASTER = 1;
+    
+        /**
+         * Role value indicating that the controller is in the SLAVE role.
+         */
+        public static final int NX_ROLE_SLAVE = 2;
+
+        protected int role;
+
+     ...
+}}}
+There is more to this class, but that is covered later, under [#serial serialization].   
+
+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 (which we cover next), the message implementation may be structured as needed. 
 
 === 2.2 Message Registration ===
@@ -139 +179 @@
 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)--->|                             
+                     |<-Vendor ID->||<-dataType->||<---payload(4)--->|                             
     [OpenFlow Header][ 0x00002320  ][    10|11   ][      0|1|2       ]
 }}} 
@@ -181 +221 @@
     }
 }}} 
-
-== 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.  
+Now that we have vendor data, we can complete the full !OpenFlow message -- which brings us to the next section.  
+
+== 3. The OpenFlow 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 (e.g. registered) type of vendor data.   
+
+The class `OFVendor` implements the full !OpenFlow vendor message. `OFVendor` itself is a subclass of `OFMessage`, which implements the generic !OpenFlow message header. As with other !OpenFlow messages, the vendor messages are received by the controller via the `OFChannelHandler`, an inner class of `Controller`, and sent out via the ''write()'' methods in `OFSwitchImpl`, the class that represents a switch connected to the controller. Description of the full system is better left to another tutorial, as it will detract from our main topic.  
 
 === 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.   
+We sidestep from the Nicira messages for this section to look at `OFVendorTest`, the unit test for Vendor messages, found in `/src/test/java` of Floodlight source. Aside from their [http://www.openflowhub.org/display/floodlightcontroller/Unit+Tests intended purpose], the unit tests are fairly good references for figuring out how various components of the controller and openflowj are instantiated and/or used. 
+
+We can reference the first few lines of ''testVendorData()'' of `OFVendorTest` to see how a vendor message may be constructed in full. 
+{{{
+    OFVendor msg = makeVendorMessage(ACME_VENDOR_ID);                         (1)
+    OFVendorData vendorData = new AcmeVendorData1((short)11, (short)22);      (2) 
+    msg.setVendorData(vendorData);                                            (3)
+    msg.setLengthU(OFVendor.MINIMUM_LENGTH + vendorData.getLength());         (4)
+}}}
+We see four basic steps to the process:
+ 1. Create an "empty" OFVendor message. the method ''makeVendorMessage()'' is a helper function: 
+ {{{
+     private OFVendor makeVendorMessage(int vendor) {
+         OFVendor msg = (OFVendor) messageFactory.getMessage(OFType.VENDOR);   (1)
+         msg.setVendorDataFactory(new BasicFactory());                         (2)
+         msg.setVendor(vendor);                                                (3)
+         return msg;
+     }
+ }}}
+ This function is (1) wired to an !OpenFlow message factory that supplies us with the empty OFVendor message, and also does some prep work on the OFVendor message, such as (2) setting its message factory and (3) the Vendor ID field.   
+ 2. Create the vendor data, and set its fields as needed. 
+ 3. set the vendor data of the message created in 1. to the vendor data created in 2. 
+ 4. set the length of the total message. OFVendor.MINIMUM_LENGTH counts just the length of the !OpenFlow header (8 bytes) and the Vendor ID and is 12 bytes.  
+
+At this point, the message is ready to be sent. Sending the message to a switch is a one-liner, in theory:
+{{{
+    sw.write(msg, null);
+}}}
 
 === 3.2 Reading message contents ===
+`OFVendor` provides the following methods for deconstructing a message:
+ * getVendor() : return the Vendor ID 
+ * getVendorData() : return the vendor data 
+Once the vendor data is extracted, it may be cast to the appropriate message type for further parsing. A good reference for this process is the method ''handleVendorMessage()'', found in `OFChannelHandler`. It extracts the dataType from the message, and passes it to a switch statement to cast it to the correct message type and to pass it to appropriate methods: 
+{{{
+    int dataType = niciraVendorData.getDataType();
+    switch (dataType) {
+        case OFRoleReplyVendorData.NXT_ROLE_REPLY:
+             OFRoleReplyVendorData roleReplyVendorData =
+                    (OFRoleReplyVendorData) niciraVendorData;
+             handleRoleReplyMessage(vendorMessage, 
+                                   roleReplyVendorData);
+             break;
+        default:
+             log.warn("Unhandled Nicira VENDOR message; " +
+                      "data type = {}", dataType);
+             break;
+    }
+}}}
+This method processes all vendor messages that the controller receives. As it is currently implemented to handle only Nicira vendor messages, it must be modified to also handle your messages. This can be as simple as adding your Vendor ID to the first switch statement in the method:
+{{{
+    int vendor = vendorMessage.getVendor();
+    switch (vendor) {
+        case OFNiciraVendorData.NX_VENDOR_ID:
+         ...
+             break;
+        case YourVendorData.VENDOR_ID:
+         ....
+             break; 
+        default:
+            log.warn("Unhandled VENDOR message; vendor id = {}", vendor);
+            break;
+    }
+}}}