ofpbuf: Abstract 'l2' pointer and document usage conventions.

Rename 'l2' to 'frame' and add new ofpbuf_set_frame() and ofpbuf_l2().
ofpbuf_set_frame() alse resets all the layer offsets.  ofpbuf_l2()
returns NULL if the packet has no Ethernet header, as indicated either
by unset l3 offset or NULL frame pointer.  Callers of ofpbuf_l2() are
supposed to check the return value, unless they can otherwise be sure
that the packet has a valid Ethernet header.

The recent commit 437d0d22 made some assumptions that were not valid
regarding the use of the 'l2' pointer in rconn module and by
compose_rarp().  This is now fixed as follows: rconn now relies on the
fact that once OpenFlow messages are given to rconn for transport, the
frame pointer is no longer needed to refer to the OpenFlow header; and
compose_rarp() now sets the frame pointer and offsets as expected.

In addition to storing network frames, ofpbufs are also used for
handling OpenFlow messages and action lists.  lib/ofpbuf.h now has a
comment documenting the current usage conventions and invariants.

Signed-off-by: Jarno Rajahalme <jrajahalme@nicira.com>
Signed-off-by: Ben Pfaff <blp@nicira.com>

1 files changed, 36 insertions, 36 deletions

diff --git a/lib/ofp-msgs.c b/lib/ofp-msgs.c
index fc91aaf1d..b67e47a7c 100644
--- a/lib/ofp-msgs.c
+++ b/lib/ofp-msgs.c
@@ -371,17 +371,17 @@ ofpraw_decode_assert(const struct ofp_header *oh)
 }
 
 /* Determines the OFPRAW_* type of the OpenFlow message in 'msg', which starts
- * at 'ofpbuf_data(msg)' and has length 'ofpbuf_size(msg)' bytes.  On success, returns 0 and
- * stores the type into '*rawp'.  On failure, returns an OFPERR_* error code
- * and zeros '*rawp'.
+ * at 'ofpbuf_data(msg)' and has length 'ofpbuf_size(msg)' bytes.  On success,
+ * returns 0 and stores the type into '*rawp'.  On failure, returns an OFPERR_*
+ * error code and zeros '*rawp'.
  *
  * This function checks that the message has a valid length for its particular
  * type of message, and returns an error if not.
  *
  * In addition to setting '*rawp', this function pulls off the OpenFlow header
  * (including the stats headers, vendor header, and any subtype header) with
- * ofpbuf_pull().  It also sets 'msg->l2' to the start of the OpenFlow header
- * and 'msg->l3' just beyond the headers (that is, to the final value of
+ * ofpbuf_pull().  It also sets 'msg->frame' to the start of the OpenFlow
+ * header and 'msg->l3' just beyond the headers (that is, to the final value of
  * ofpbuf_data(msg)). */
 enum ofperr
 ofpraw_pull(enum ofpraw *rawp, struct ofpbuf *msg)
@@ -399,8 +399,8 @@ ofpraw_pull(enum ofpraw *rawp, struct ofpbuf *msg)
     enum ofpraw raw;
 
     /* Set default outputs. */
-    msg->l2 = ofpbuf_data(msg);
-    ofpbuf_set_l3(msg, ofpbuf_data(msg));
+    msg->frame = ofpbuf_data(msg);
+    ofpbuf_set_l3(msg, msg->frame);
     *rawp = 0;
 
     len = ofpbuf_size(msg);
@@ -416,7 +416,7 @@ ofpraw_pull(enum ofpraw *rawp, struct ofpbuf *msg)
 
     info = raw_info_get(raw);
     instance = raw_instance_get(info, hdrs.version);
-    msg->l2 = ofpbuf_pull(msg, instance->hdrs_len);
+    msg->frame = ofpbuf_pull(msg, instance->hdrs_len);
     ofpbuf_set_l3(msg, ofpbuf_data(msg));
 
     min_len = instance->hdrs_len + info->min_body;
@@ -511,10 +511,10 @@ static void ofpraw_put__(enum ofpraw, uint8_t version, ovs_be32 xid,
  * Each 'raw' value is valid only for certain OpenFlow versions.  The caller
  * must specify a valid (raw, version) pair.
  *
- * In the returned ofpbuf, 'l2' points to the beginning of the OpenFlow header
- * and 'l3' points just after it, to where the message's body will start.  The
- * caller must actually allocate the body into the space reserved for it,
- * e.g. with ofpbuf_put_uninit().
+ * In the returned ofpbuf, 'frame' points to the beginning of the
+ * OpenFlow header and 'l3' points just after it, to where the
+ * message's body will start.  The caller must actually allocate the
+ * body into the space reserved for it, e.g. with ofpbuf_put_uninit().
  *
  * The caller owns the returned ofpbuf and must free it when it is no longer
  * needed, e.g. with ofpbuf_delete(). */
@@ -558,10 +558,10 @@ ofpraw_alloc_reply(enum ofpraw raw, const struct ofp_header *request,
  * value.  Every stats request has a corresponding reply, so the (raw, version)
  * pairing pitfalls of the other ofpraw_alloc_*() functions don't apply here.
  *
- * In the returned ofpbuf, 'l2' points to the beginning of the OpenFlow header
- * and 'l3' points just after it, to where the message's body will start.  The
- * caller must actually allocate the body into the space reserved for it,
- * e.g. with ofpbuf_put_uninit().
+ * In the returned ofpbuf, 'frame' points to the beginning of the
+ * OpenFlow header and 'l3' points just after it, to where the
+ * message's body will start.  The caller must actually allocate the
+ * body into the space reserved for it, e.g. with ofpbuf_put_uninit().
  *
  * The caller owns the returned ofpbuf and must free it when it is no longer
  * needed, e.g. with ofpbuf_delete(). */
@@ -591,7 +591,7 @@ ofpraw_alloc_stats_reply(const struct ofp_header *request,
  * Each 'raw' value is valid only for certain OpenFlow versions.  The caller
  * must specify a valid (raw, version) pair.
  *
- * Upon return, 'buf->l2' points to the beginning of the OpenFlow header and
+ * Upon return, 'buf->frame' points to the beginning of the OpenFlow header and
  * 'buf->l3' points just after it, to where the message's body will start.  The
  * caller must actually allocating the body into the space reserved for it,
  * e.g. with ofpbuf_put_uninit(). */
@@ -631,10 +631,10 @@ ofpraw_put_reply(enum ofpraw raw, const struct ofp_header *request,
  * value.  Every stats request has a corresponding reply, so the (raw, version)
  * pairing pitfalls of the other ofpraw_alloc_*() functions don't apply here.
  *
- * In the returned ofpbuf, 'l2' points to the beginning of the OpenFlow header
- * and 'l3' points just after it, to where the message's body will start.  The
- * caller must actually allocate the body into the space reserved for it,
- * e.g. with ofpbuf_put_uninit().
+ * In the returned ofpbuf, 'frame' points to the beginning of the
+ * OpenFlow header and 'l3' points just after it, to where the
+ * message's body will start.  The caller must actually allocate the
+ * body into the space reserved for it, e.g. with ofpbuf_put_uninit().
  *
  * The caller owns the returned ofpbuf and must free it when it is no longer
  * needed, e.g. with ofpbuf_delete(). */
@@ -664,17 +664,17 @@ ofpraw_put__(enum ofpraw raw, uint8_t version, ovs_be32 xid,
 
     ofpbuf_prealloc_tailroom(buf, (instance->hdrs_len + info->min_body
                                    + extra_tailroom));
-    buf->l2 = ofpbuf_put_uninit(buf, instance->hdrs_len);
+    buf->frame = ofpbuf_put_uninit(buf, instance->hdrs_len);
     ofpbuf_set_l3(buf, ofpbuf_tail(buf));
 
-    oh = buf->l2;
+    oh = buf->frame;
     oh->version = version;
     oh->type = hdrs->type;
     oh->length = htons(ofpbuf_size(buf));
     oh->xid = xid;
 
     if (hdrs->type == OFPT_VENDOR) {
-        struct nicira_header *nh = buf->l2;
+        struct nicira_header *nh = buf->frame;
 
         ovs_assert(hdrs->vendor == NX_VENDOR_ID);
         nh->vendor = htonl(hdrs->vendor);
@@ -682,17 +682,17 @@ ofpraw_put__(enum ofpraw raw, uint8_t version, ovs_be32 xid,
     } else if (version == OFP10_VERSION
                && (hdrs->type == OFPT10_STATS_REQUEST ||
                    hdrs->type == OFPT10_STATS_REPLY)) {
-        struct ofp10_stats_msg *osm = buf->l2;
+        struct ofp10_stats_msg *osm = buf->frame;
 
         osm->type = htons(hdrs->stat);
         osm->flags = htons(0);
 
         if (hdrs->stat == OFPST_VENDOR) {
-            struct ofp10_vendor_stats_msg *ovsm = buf->l2;
+            struct ofp10_vendor_stats_msg *ovsm = buf->frame;
 
             ovsm->vendor = htonl(hdrs->vendor);
             if (hdrs->vendor == NX_VENDOR_ID) {
-                struct nicira10_stats_msg *nsm = buf->l2;
+                struct nicira10_stats_msg *nsm = buf->frame;
 
                 nsm->subtype = htonl(hdrs->subtype);
                 memset(nsm->pad, 0, sizeof nsm->pad);
@@ -703,18 +703,18 @@ ofpraw_put__(enum ofpraw raw, uint8_t version, ovs_be32 xid,
     } else if (version != OFP10_VERSION
                && (hdrs->type == OFPT11_STATS_REQUEST ||
                    hdrs->type == OFPT11_STATS_REPLY)) {
-        struct ofp11_stats_msg *osm = buf->l2;
+        struct ofp11_stats_msg *osm = buf->frame;
 
         osm->type = htons(hdrs->stat);
         osm->flags = htons(0);
         memset(osm->pad, 0, sizeof osm->pad);
 
         if (hdrs->stat == OFPST_VENDOR) {
-            struct ofp11_vendor_stats_msg *ovsm = buf->l2;
+            struct ofp11_vendor_stats_msg *ovsm = buf->frame;
 
             ovsm->vendor = htonl(hdrs->vendor);
             if (hdrs->vendor == NX_VENDOR_ID) {
-                struct nicira11_stats_msg *nsm = buf->l2;
+                struct nicira11_stats_msg *nsm = buf->frame;
 
                 nsm->subtype = htonl(hdrs->subtype);
             } else {
@@ -790,17 +790,17 @@ ofptype_decode(enum ofptype *typep, const struct ofp_header *oh)
 }
 
 /* Determines the OFPTYPE_* type of the OpenFlow message in 'msg', which starts
- * at 'ofpbuf_data(msg)' and has length 'ofpbuf_size(msg)' bytes.  On success, returns 0 and
- * stores the type into '*typep'.  On failure, returns an OFPERR_* error code
- * and zeros '*typep'.
+ * at 'ofpbuf_data(msg)' and has length 'ofpbuf_size(msg)' bytes.  On success,
+ * returns 0 and stores the type into '*typep'.  On failure, returns an
+ * OFPERR_* error code and zeros '*typep'.
  *
  * This function checks that the message has a valid length for its particular
  * type of message, and returns an error if not.
  *
  * In addition to setting '*typep', this function pulls off the OpenFlow header
  * (including the stats headers, vendor header, and any subtype header) with
- * ofpbuf_pull().  It also sets 'msg->l2' to the start of the OpenFlow header
- * and 'msg->l3' just beyond the headers (that is, to the final value of
+ * ofpbuf_pull().  It also sets 'msg->frame' to the start of the OpenFlow
+ * header and 'msg->l3' just beyond the headers (that is, to the final value of
  * ofpbuf_data(msg)). */
 enum ofperr
 ofptype_pull(enum ofptype *typep, struct ofpbuf *buf)
@@ -893,7 +893,7 @@ ofpmp_reserve(struct list *replies, size_t len)
 
         next = ofpbuf_new(MAX(1024, hdrs_len + len));
         ofpbuf_put(next, ofpbuf_data(msg), hdrs_len);
-        next->l2 = ofpbuf_data(next);
+        next->frame = ofpbuf_data(next);
         ofpbuf_set_l3(next, ofpbuf_tail(next));
         list_push_back(replies, &next->list_node);