java_gen: Add documentation on OFPortBitmap, unit test clarity fix
Limit the unit test use the to 127 (valid) ports for clarity.
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);