Improve comments on interpretation of sFlow sampling probabilities.

Suggested by Justin Pettit.

diff --git a/datapath/datapath.h b/datapath/datapath.h
index c610312..7fa90f3 100644 (file)
--- a/datapath/datapath.h
+++ b/datapath/datapath.h
@@ -127,9 +127,9 @@ struct dp_port_group {
  * always exists, other ports may be %NULL.
  * @port_list: List of all ports in @ports in arbitrary order.
  * @stats_percpu: Per-CPU datapath statistics.
- * @sflow_probability: Probability of sampling a packet to the %ODPL_SFLOW
- * queue, where 0 means never sample, UINT_MAX means always sample, and
- * other values are intermediate probabilities.
+ * @sflow_probability: Number of packets out of UINT_MAX to sample to the
+ * %ODPL_SFLOW queue, e.g. (@sflow_probability/UINT_MAX) is the probability of
+ * sampling a given packet.
  */
 struct datapath {
        struct mutex mutex;

diff --git a/lib/dpif-provider.h b/lib/dpif-provider.h
index eade868..c33faf1 100644 (file)
--- a/lib/dpif-provider.h
+++ b/lib/dpif-provider.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009 Nicira Networks.
+ * Copyright (c) 2009, 2010 Nicira Networks.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -282,8 +282,9 @@ struct dpif_class {
      * Return value is 0 or a positive errno value.  EOPNOTSUPP indicates that
      * the datapath does not support sFlow, as does a null pointer.
      *
-     * A probability of 0 means sample no packets, UINT32_MAX means sample
-     * every packet, and other values are intermediate probabilities. */
+     * '*probability' is expressed as the number of packets out of UINT_MAX to
+     * sample, e.g. probability/UINT_MAX is the probability of sampling a given
+     * packet. */
     int (*get_sflow_probability)(const struct dpif *dpif,
                                  uint32_t *probability);
 
@@ -291,8 +292,9 @@ struct dpif_class {
      * is 0 or a positive errno value.  EOPNOTSUPP indicates that the datapath
      * does not support sFlow, as does a null pointer.
      *
-     * A probability of 0 means sample no packets, UINT32_MAX means sample
-     * every packet, and other values are intermediate probabilities. */
+     * 'probability' is expressed as the number of packets out of UINT_MAX to
+     * sample, e.g. probability/UINT_MAX is the probability of sampling a given
+     * packet. */
     int (*set_sflow_probability)(struct dpif *dpif, uint32_t probability);
 
     /* Attempts to receive a message from 'dpif'.  If successful, stores the

diff --git a/lib/dpif.c b/lib/dpif.c
index 8bca124..06f793c 100644 (file)
--- a/lib/dpif.c
+++ b/lib/dpif.c
@@ -845,9 +845,9 @@ dpif_recv_set_mask(struct dpif *dpif, int listen_mask)
     return error;
 }
 
-/* Retrieve the sFlow sampling probability.  A probability of 0 means sample no
- * packets, UINT32_MAX means sample every packet, and other values are
- * intermediate probabilities.
+/* Retrieve the sFlow sampling probability.  '*probability' is expressed as the
+ * number of packets out of UINT_MAX to sample, e.g. probability/UINT_MAX is
+ * the probability of sampling a given packet.
  *
  * Returns 0 if successful, otherwise a positive errno value.  EOPNOTSUPP
  * indicates that 'dpif' does not support sFlow sampling. */
@@ -864,9 +864,9 @@ dpif_get_sflow_probability(const struct dpif *dpif, uint32_t *probability)
     return error;
 }
 
-/* Set the sFlow sampling probability.  A probability of 0 means sample no
- * packets, UINT32_MAX means sample every packet, and other values are
- * intermediate probabilities.
+/* Set the sFlow sampling probability.  'probability' is expressed as the
+ * number of packets out of UINT_MAX to sample, e.g. probability/UINT_MAX is
+ * the probability of sampling a given packet.
  *
  * Returns 0 if successful, otherwise a positive errno value.  EOPNOTSUPP
  * indicates that 'dpif' does not support sFlow sampling. */