diff --git a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/OFPortBitMap.java b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/OFPortBitMap.java
index dd88ea6..49c8c4e 100644
--- a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/OFPortBitMap.java
+++ b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/OFPortBitMap.java
@@ -1,13 +1,39 @@
 package org.projectfloodlight.openflow.types;
 
 
+/** User-facing object representing a bitmap of ports that can be matched on.
+ *  This is implemented by the custom BSN OXM type of_oxm_bsn_in_ports_182.
+ *
+ *  You can call set() on the builder for all the Ports you want to match on
+ *  and unset to exclude the port.
+ *
+ *  <b>Implementation note:</b> to comply with the matching semantics of OXM (which is a logical "AND" not "OR")
+ *  the underlying match uses a data format which is very unintuitive. The value is always
+ *  0, and the mask has the bits set for the ports that should <b>NOT</b> be included in the
+ *  range.
+ *
+ *  For the curious: We transformed the bitmap (a logical OR) problem into a logical
+ *  AND NOT problem.
+ *
+ *  We logically mean:   Inport is 1 OR 3
+ *  We technically say:  Inport IS NOT 2 AND IS NOT 4 AND IS NOT 5 AND IS NOT ....
+ *  The second term cannot be represented in OXM, the second can.
+ *
+ *  That said, all that craziness is hidden from the user of this object.
+ * @author Andreas Wundsam <andreas.wundsam@bigswitch.com>
+ */
 public class OFPortBitMap extends Masked<OFBitMask128> {
 
     private OFPortBitMap(OFBitMask128 mask) {
         super(OFBitMask128.NONE, mask);
     }
 
+    /** @return whether or not the given port is logically included in the
+     *  match, i.e., whether a packet from in-port <emph>port</emph> be matched by
+     *  this OXM.
+     */
     public boolean isOn(OFPort port) {
+        // see the implementation note above about the logical inversion of the mask
         return !(this.mask.isOn(port.getPortNumber()));
     }
 
@@ -39,15 +65,30 @@
 
         }
 
+        /** @return whether or not the given port is logically included in the
+         *  match, i.e., whether a packet from in-port <emph>port</emph> be matched by
+         *  this OXM.
+         */
         public boolean isOn(OFPort port) {
+            // see the implementation note above about the logical inversion of the mask
             return !(OFBitMask128.isBitOn(raw1, raw2, port.getPortNumber()));
         }
 
+        /** remove this port from the match, i.e., packets from this in-port
+         *  will NOT be matched.
+         */
         public Builder unset(OFPort port) {
+            // see the implementation note above about the logical inversion of the mask
             int bit = port.getPortNumber();
-            if (bit < 0 || bit >= 127) // MAX PORT IS 127
+            if (bit < 0 || bit > 127)
                 throw new IndexOutOfBoundsException("Port number is out of bounds");
-            if (bit < 64) {
+            else if (bit == 127)
+                // the highest order bit in the bitmask is reserved. The switch will
+                // set that bit for all ports >= 127. The reason is that we don't want
+                // the OFPortMap to match all ports out of its range (i.e., a packet
+                // coming in on port 181 would match *any* OFPortMap).
+                throw new IndexOutOfBoundsException("The highest order bit in the bitmask is reserved.");
+            else if (bit < 64) {
                 raw2 |= ((long)1 << bit);
             } else {
                 raw1 |= ((long)1 << (bit - 64));
@@ -55,11 +96,21 @@
             return this;
         }
 
+        /** add this port from the match, i.e., packets from this in-port
+         *  will NOT be matched.
+         */
         public Builder set(OFPort port) {
+            // see the implementation note above about the logical inversion of the mask
             int bit = port.getPortNumber();
-            if (bit < 0 || bit >= 127)
+            if (bit < 0 || bit > 127)
                 throw new IndexOutOfBoundsException("Port number is out of bounds");
-            if (bit < 64) {
+            else if (bit == 127)
+                // the highest order bit in the bitmask is reserved. The switch will
+                // set that bit for all ports >= 127. The reason is that we don't want
+                // the OFPortMap to match all ports out of its range (i.e., a packet
+                // coming in on port 181 would match *any* OFPortMap).
+                throw new IndexOutOfBoundsException("The highest order bit in the bitmask is reserved.");
+            else if (bit < 64) {
                 raw2 &= ~((long)1 << bit);
             } else {
                 raw1 &= ~((long)1 << (bit - 64));
diff --git a/java_gen/pre-written/src/test/java/org/projectfloodlight/openflow/types/OFPortBitMapTest.java b/java_gen/pre-written/src/test/java/org/projectfloodlight/openflow/types/OFPortBitMapTest.java
index b18d0eb..7f5ab5d 100644
--- a/java_gen/pre-written/src/test/java/org/projectfloodlight/openflow/types/OFPortBitMapTest.java
+++ b/java_gen/pre-written/src/test/java/org/projectfloodlight/openflow/types/OFPortBitMapTest.java
@@ -9,14 +9,14 @@
 
     @Test
     public void testOFPortBitMap() {
-        Boolean[] on = new Boolean[128];
-        for (int i = 0; i < 128; i++) {
+        Boolean[] on = new Boolean[127];
+        for (int i = 0; i < 127; i++) {
             on[i] = false;
         }
 
         OFPortBitMap.Builder builder = new OFPortBitMap.Builder();
 
-        for (int i = 0; i < 128; i += 3) {
+        for (int i = 0; i < 127; i += 3) {
             OFPort p = OFPort.of(i);
             builder.set(p);
             on[p.getPortNumber()] = true;
@@ -25,28 +25,28 @@
         // Test that all ports that were added are actually on, and all other ports are off
         OFPortBitMap portmap = builder.build();
         //System.out.println(portmap);
-        Boolean[] actual = new Boolean[128];
-        for (int i = 0; i < 128; i++) {
+        Boolean[] actual = new Boolean[127];
+        for (int i = 0; i < 127; i++) {
             actual[i] = false;
         }
-        for (int i = 0; i < 128; i++) {
+        for (int i = 0; i < 127; i++) {
             actual[i] = portmap.isOn(OFPort.of(i));
         }
         assertArrayEquals(on, actual);
 
         // Turn some ports off
-        for (int i = 0; i < 128; i += 7) {
+        for (int i = 0; i < 127; i += 7) {
             on[i] = false;
             builder.unset(OFPort.of(i));
         }
 
         // Test again
         portmap = builder.build();
-        actual = new Boolean[128];
-        for (int i = 0; i < 128; i++) {
+        actual = new Boolean[127];
+        for (int i = 0; i < 127; i++) {
             actual[i] = false;
         }
-        for (int i = 0; i < 128; i++) {
+        for (int i = 0; i < 127; i++) {
             actual[i] = portmap.isOn(OFPort.of(i));
         }
         assertArrayEquals(on, actual);