dpif: Update documentation for RCU-protected actions.

The userspace datapath returns RCU-protected actions from flow_get() and flow_dump_next(). This doesn't cause any trouble for current users of these functions, but it imposes additional constraints on their use. This patch makes the dpif documentation more explicit about how the results of these functions can be used. Signed-off-by: Joe Stringer <[email protected]> Acked-by: Ben Pfaff <[email protected]>
robin-zhou · Jul 16, 2014 · 58df55c · 58df55c
1 parent bdba194
commit 58df55c
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 6 deletions.
diff --git a/lib/dpif-netdev.c b/lib/dpif-netdev.c
@@ -1466,7 +1466,6 @@ dpif_netdev_flow_dump_thread_destroy(struct dpif_flow_dump_thread *thread_)
     free(thread);
 }
 
-/* XXX the caller must use 'actions' without quiescing */
 static int
 dpif_netdev_flow_dump_next(struct dpif_flow_dump_thread *thread_,
                            struct dpif_flow *flows, int max_flows)

diff --git a/lib/dpif-provider.h b/lib/dpif-provider.h
@@ -253,11 +253,13 @@ struct dpif_class {
      *
      * If 'maskp' is nonnull, then on success '*maskp' will point to the
      * Netlink attributes for the flow's mask. '*mask_len' will be set to the
-     * length of the mask attributes.
+     * length of the mask attributes. Implementations may opt to point 'maskp'
+     * at RCU-protected data rather than making a copy in '*bufp'.
      *
      * If 'actionsp' is nonnull, then on success '*actionsp' will point to the
      * Netlink attributes for the flow's actions. '*actions_len' will be set to
-     * the length of the actions attributes.
+     * the length of the actions attributes. Implementations may opt to point
+     * 'actionsp' at RCU-protected data rather than making a copy in '*bufp'.
      *
      * If 'stats' is nonnull, then on success it must be updated with the
      * flow's statistics. */

diff --git a/lib/dpif.c b/lib/dpif.c
@@ -842,7 +842,11 @@ dpif_flow_flush(struct dpif *dpif)
  * On success, 'flow' will be populated with the mask, actions and stats for
  * the datapath flow corresponding to 'key'. The mask and actions will point
  * within '*bufp'.
- */
+ *
+ * Implementations may opt to point 'flow->mask' and/or 'flow->actions' at
+ * RCU-protected data rather than making a copy of them. Therefore, callers
+ * that wish to hold these over quiescent periods must make a copy of these
+ * fields before quiescing. */
 int
 dpif_flow_get(const struct dpif *dpif,
               const struct nlattr *key, size_t key_len,
@@ -1030,8 +1034,9 @@ dpif_flow_dump_thread_destroy(struct dpif_flow_dump_thread *thread)
  *
  * All of the data stored into 'flows' is owned by the datapath, not by the
  * caller, and the caller must not modify or free it.  The datapath guarantees
- * that it remains accessible and unchanged until at least the next call to
- * dpif_flow_dump_next() for 'thread'. */
+ * that it remains accessible and unchanged until the first of:
+ *  - The next call to dpif_flow_dump_next() for 'thread', or
+ *  - The next rcu quiescent period. */
 int
 dpif_flow_dump_next(struct dpif_flow_dump_thread *thread,
                     struct dpif_flow *flows, int max_flows)