DPDK patches and discussions
 help / color / mirror / Atom feed
From: Stephen Hemminger <stephen@networkplumber.org>
To: cristian.dumitrescu@intel.com
Cc: dev@dpdk.org, Stephen Hemminger <shemming@brocade.com>
Subject: [dpdk-dev] [PATCH v2 02/10] sched: cleanup comments
Date: Fri, 13 Nov 2015 09:58:28 -0800	[thread overview]
Message-ID: <1447437516-19152-3-git-send-email-stephen@networkplumber.org> (raw)
In-Reply-To: <1447437516-19152-1-git-send-email-stephen@networkplumber.org>

From: Stephen Hemminger <shemming@brocade.com>

Break block comments that exceed common practice for line length.
Shorten wording for obvious things.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 lib/librte_sched/rte_sched.c |   8 +-
 lib/librte_sched/rte_sched.h | 221 +++++++++++++++++++++++++------------------
 2 files changed, 135 insertions(+), 94 deletions(-)

diff --git a/lib/librte_sched/rte_sched.c b/lib/librte_sched/rte_sched.c
index 9478798..52a22d5 100644
--- a/lib/librte_sched/rte_sched.c
+++ b/lib/librte_sched/rte_sched.c
@@ -346,7 +346,8 @@ rte_sched_port_check_params(struct rte_sched_port_params *params)
 		return -7;
 	}
 
-	/* qsize: non-zero, power of 2, no bigger than 32K (due to 16-bit read/write pointers) */
+	/* qsize: non-zero, power of 2,
+	 * no bigger than 32K (due to 16-bit read/write pointers) */
 	for (i = 0; i < RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE; i ++) {
 		uint16_t qsize = params->qsize[i];
 
@@ -1318,7 +1319,8 @@ rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint
 
 #else
 
-/* The enqueue function implements a 4-level pipeline with each stage processing
+/*
+ * The enqueue function implements a 4-level pipeline with each stage processing
  * two different packets. The purpose of using a pipeline is to hide the latency
  * of prefetching the data structures. The naming convention is presented in the
  * diagram below:
@@ -1329,7 +1331,7 @@ rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint
  * ----->|_______|----->|_______|----->|_______|----->|_______|----->
  *   p01            p11            p21            p31
  *
- ***/
+ */
 int
 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts)
 {
diff --git a/lib/librte_sched/rte_sched.h b/lib/librte_sched/rte_sched.h
index 9bdd51c..c0f4ad3 100644
--- a/lib/librte_sched/rte_sched.h
+++ b/lib/librte_sched/rte_sched.h
@@ -42,39 +42,48 @@ extern "C" {
  * @file
  * RTE Hierarchical Scheduler
  *
- * The hierarchical scheduler prioritizes the transmission of packets from different
- * users and traffic classes according to the Service Level Agreements (SLAs) defined
- * for the current network node.
+ * The hierarchical scheduler prioritizes the transmission of packets
+ * from different users and traffic classes according to the Service
+ * Level Agreements (SLAs) defined for the current network node.
  *
- * The scheduler supports thousands of packet queues grouped under a 5-level hierarchy:
+ * The scheduler supports thousands of packet queues grouped under a
+ * 5-level hierarchy:
  *     1. Port:
  *           - Typical usage: output Ethernet port;
- *           - Multiple ports are scheduled in round robin order with equal priority;
+ *           - Multiple ports are scheduled in round robin order with
+ *	    equal priority;
  *     2. Subport:
  *           - Typical usage: group of users;
- *           - Traffic shaping using the token bucket algorithm (one bucket per subport);
+ *           - Traffic shaping using the token bucket algorithm
+ *	    (one bucket per subport);
  *           - Upper limit enforced per traffic class at subport level;
- *           - Lower priority traffic classes able to reuse subport bandwidth currently
- *             unused by higher priority traffic classes of the same subport;
- *           - When any subport traffic class is oversubscribed (configuration time
- *             event), the usage of subport member pipes with high demand for that
- *             traffic class pipes is truncated to a dynamically adjusted value with no
+ *           - Lower priority traffic classes able to reuse subport
+ *	    bandwidth currently unused by higher priority traffic
+ *	    classes of the same subport;
+ *           - When any subport traffic class is oversubscribed
+ *	    (configuration time event), the usage of subport member
+ *	    pipes with high demand for thattraffic class pipes is
+ *	    truncated to a dynamically adjusted value with no
  *             impact to low demand pipes;
  *     3. Pipe:
  *           - Typical usage: individual user/subscriber;
- *           - Traffic shaping using the token bucket algorithm (one bucket per pipe);
+ *           - Traffic shaping using the token bucket algorithm
+ *	    (one bucket per pipe);
  *     4. Traffic class:
- *           - Traffic classes of the same pipe handled in strict priority order;
+ *           - Traffic classes of the same pipe handled in strict
+ *	    priority order;
  *           - Upper limit enforced per traffic class at the pipe level;
- *           - Lower priority traffic classes able to reuse pipe bandwidth currently
- *             unused by higher priority traffic classes of the same pipe;
+ *           - Lower priority traffic classes able to reuse pipe
+ *	    bandwidth currently unused by higher priority traffic
+ *	    classes of the same pipe;
  *     5. Queue:
- *           - Typical usage: queue hosting packets from one or multiple connections
- *             of same traffic class belonging to the same user;
- *           - Weighted Round Robin (WRR) is used to service the queues within same
- *             pipe traffic class.
+ *           - Typical usage: queue hosting packets from one or
+ *	    multiple connections of same traffic class belonging to
+ *	    the same user;
+ *           - Weighted Round Robin (WRR) is used to service the
+ *	    queues within same pipe traffic class.
  *
- ***/
+ */
 
 #include <sys/types.h>
 #include <rte_mbuf.h>
@@ -85,7 +94,9 @@ extern "C" {
 #include "rte_red.h"
 #endif
 
-/** Number of traffic classes per pipe (as well as subport). Cannot be changed. */
+/** Number of traffic classes per pipe (as well as subport).
+ * Cannot be changed.
+ */
 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE    4
 
 /** Number of queues per pipe traffic class. Cannot be changed. */
@@ -96,100 +107,123 @@ extern "C" {
 	(RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE *     \
 	RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS)
 
-/** Maximum number of pipe profiles that can be defined per port. Compile-time configurable.*/
+/** Maximum number of pipe profiles that can be defined per port.
+ * Compile-time configurable.
+ */
 #ifndef RTE_SCHED_PIPE_PROFILES_PER_PORT
 #define RTE_SCHED_PIPE_PROFILES_PER_PORT      256
 #endif
 
-/** Ethernet framing overhead. Overhead fields per Ethernet frame:
-   1. Preamble:                             7 bytes;
-   2. Start of Frame Delimiter (SFD):       1 byte;
-   3. Frame Check Sequence (FCS):           4 bytes;
-   4. Inter Frame Gap (IFG):               12 bytes.
-The FCS is considered overhead only if not included in the packet length (field pkt_len
-of struct rte_mbuf). */
+/*
+ * Ethernet framing overhead. Overhead fields per Ethernet frame:
+ * 1. Preamble:                             7 bytes;
+ * 2. Start of Frame Delimiter (SFD):       1 byte;
+ * 3. Frame Check Sequence (FCS):           4 bytes;
+ * 4. Inter Frame Gap (IFG):               12 bytes.
+ *
+ * The FCS is considered overhead only if not included in the packet
+ * length (field pkt_len of struct rte_mbuf).
+ */
 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT      24
 #endif
 
-/** Subport configuration parameters. The period and credits_per_period parameters are measured
-in bytes, with one byte meaning the time duration associated with the transmission of one byte
-on the physical medium of the output port, with pipe or pipe traffic class rate (measured as
-percentage of output port rate) determined as credits_per_period divided by period. One credit
-represents one byte. */
+/*
+ * Subport configuration parameters. The period and credits_per_period
+ * parameters are measured in bytes, with one byte meaning the time
+ * duration associated with the transmission of one byte on the
+ * physical medium of the output port, with pipe or pipe traffic class
+ * rate (measured as percentage of output port rate) determined as
+ * credits_per_period divided by period. One credit represents one
+ * byte.
+ */
 struct rte_sched_subport_params {
 	/* Subport token bucket */
-	uint32_t tb_rate;                /**< Subport token bucket rate (measured in bytes per second) */
-	uint32_t tb_size;                /**< Subport token bucket size (measured in credits) */
+	uint32_t tb_rate;                /**< Rate (measured in bytes per second) */
+	uint32_t tb_size;                /**< Size (measured in credits) */
 
 	/* Subport traffic classes */
-	uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Subport traffic class rates (measured in bytes per second) */
-	uint32_t tc_period;              /**< Enforcement period for traffic class rates (measured in milliseconds) */
+	uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
+	/**< Traffic class rates (measured in bytes per second) */
+	uint32_t tc_period;
+	/**< Enforcement period for rates (measured in milliseconds) */
 };
 
 /** Subport statistics */
 struct rte_sched_subport_stats {
 	/* Packets */
-	uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Number of packets successfully written to current
-	                                      subport for each traffic class */
-	uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Number of packets dropped by the current
-	                                      subport for each traffic class due to subport queues being full or congested*/
+	uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
+	/**< Number of packets successfully written */
+	uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
+	/**< Number of packets dropped */
 
 	/* Bytes */
-	uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Number of bytes successfully written to current
-	                                      subport for each traffic class*/
-	uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Number of bytes dropped by the current
-                                          subport for each traffic class due to subport queues being full or congested */
+	uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
+	/**< Number of bytes successfully written for each traffic class */
+	uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
+	/**< Number of bytes dropped for each traffic class */
 };
 
-/** Pipe configuration parameters. The period and credits_per_period parameters are measured
-in bytes, with one byte meaning the time duration associated with the transmission of one byte
-on the physical medium of the output port, with pipe or pipe traffic class rate (measured as
-percentage of output port rate) determined as credits_per_period divided by period. One credit
-represents one byte. */
+/*
+ * Pipe configuration parameters. The period and credits_per_period
+ * parameters are measured in bytes, with one byte meaning the time
+ * duration associated with the transmission of one byte on the
+ * physical medium of the output port, with pipe or pipe traffic class
+ * rate (measured as percentage of output port rate) determined as
+ * credits_per_period divided by period. One credit represents one
+ * byte.
+ */
 struct rte_sched_pipe_params {
 	/* Pipe token bucket */
-	uint32_t tb_rate;                /**< Pipe token bucket rate (measured in bytes per second) */
-	uint32_t tb_size;                /**< Pipe token bucket size (measured in credits) */
+	uint32_t tb_rate;                /**< Rate (measured in bytes per second) */
+	uint32_t tb_size;                /**< Size (measured in credits) */
 
 	/* Pipe traffic classes */
-	uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Pipe traffic class rates (measured in bytes per second) */
-	uint32_t tc_period;              /**< Enforcement period for pipe traffic class rates (measured in milliseconds) */
+	uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
+	/**< Traffic class rates (measured in bytes per second) */
+	uint32_t tc_period;
+	/**< Enforcement period (measured in milliseconds) */
 #ifdef RTE_SCHED_SUBPORT_TC_OV
-	uint8_t tc_ov_weight;            /**< Weight for the current pipe in the event of subport traffic class 3 oversubscription */
+	uint8_t tc_ov_weight;		 /**< Weight Traffic class 3 oversubscription */
 #endif
 
 	/* Pipe queues */
-	uint8_t  wrr_weights[RTE_SCHED_QUEUES_PER_PIPE]; /**< WRR weights for the queues of the current pipe */
+	uint8_t  wrr_weights[RTE_SCHED_QUEUES_PER_PIPE]; /**< WRR weights */
 };
 
 /** Queue statistics */
 struct rte_sched_queue_stats {
 	/* Packets */
-	uint32_t n_pkts;                 /**< Number of packets successfully written to current queue */
-	uint32_t n_pkts_dropped;         /**< Number of packets dropped due to current queue being full or congested */
+	uint32_t n_pkts;                 /**< Packets successfully written */
+	uint32_t n_pkts_dropped;         /**< Packets dropped */
 
 	/* Bytes */
-	uint32_t n_bytes;                /**< Number of bytes successfully written to current queue */
-	uint32_t n_bytes_dropped;        /**< Number of bytes dropped due to current queue being full or congested */
+	uint32_t n_bytes;                /**< Bytes successfully written */
+	uint32_t n_bytes_dropped;        /**< Bytes dropped */
 };
 
 /** Port configuration parameters. */
 struct rte_sched_port_params {
-	const char *name;                /**< Literal string to be associated to the current port scheduler instance */
-	int socket;                      /**< CPU socket ID where the memory for port scheduler should be allocated */
-	uint32_t rate;                   /**< Output port rate (measured in bytes per second) */
-	uint32_t mtu;                    /**< Maximum Ethernet frame size (measured in bytes). Should not include the framing overhead. */
-	uint32_t frame_overhead;         /**< Framing overhead per packet (measured in bytes) */
-	uint32_t n_subports_per_port;    /**< Number of subports for the current port scheduler instance*/
-	uint32_t n_pipes_per_subport;    /**< Number of pipes for each port scheduler subport */
-	uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Packet queue size for each traffic class. All queues
-	                                      within the same pipe traffic class have the same size. Queues from
-										  different pipes serving the same traffic class have the same size. */
-	struct rte_sched_pipe_params *pipe_profiles; /**< Pipe profile table defined for current port scheduler instance.
-                                          Every pipe of the current port scheduler is configured using one of the
-										  profiles from this table. */
-	uint32_t n_pipe_profiles;        /**< Number of profiles in the pipe profile table */
+	const char *name;                /**< String to be associated */
+	int socket;                      /**< CPU socket ID */
+	uint32_t rate;                   /**< Output port rate
+					  * (measured in bytes per second) */
+	uint32_t mtu;                    /**< Maximum Ethernet frame size
+					  * (measured in bytes).
+					  * Should not include the framing overhead. */
+	uint32_t frame_overhead;         /**< Framing overhead per packet
+					  * (measured in bytes) */
+	uint32_t n_subports_per_port;    /**< Number of subports */
+	uint32_t n_pipes_per_subport;    /**< Number of pipes per subport */
+	uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
+	/**< Packet queue size for each traffic class.
+	 * All queues within the same pipe traffic class have the same
+	 * size. Queues from different pipes serving the same traffic
+	 * class have the same size. */
+	struct rte_sched_pipe_params *pipe_profiles;
+	/**< Pipe profile table.
+	 * Every pipe is configured using one of the profiles from this table. */
+	uint32_t n_pipe_profiles;        /**< Profiles in the pipe profile table */
 #ifdef RTE_SCHED_RED
 	struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][e_RTE_METER_COLORS]; /**< RED parameters */
 #endif
@@ -306,7 +340,8 @@ rte_sched_subport_read_stats(struct rte_sched_port *port,
  *   Pointer to pre-allocated subport statistics structure where the statistics
  *   counters should be stored
  * @param qlen
- *   Pointer to pre-allocated variable where the current queue length should be stored.
+ *   Pointer to pre-allocated variable where the current queue length
+ *   should be stored.
  * @return
  *   0 upon success, error code otherwise
  */
@@ -317,8 +352,8 @@ rte_sched_queue_read_stats(struct rte_sched_port *port,
 	uint16_t *qlen);
 
 /**
- * Scheduler hierarchy path write to packet descriptor. Typically called by the
- * packet classification stage.
+ * Scheduler hierarchy path write to packet descriptor. Typically
+ * called by the packet classification stage.
  *
  * @param pkt
  *   Packet descriptor handle
@@ -339,9 +374,10 @@ rte_sched_port_pkt_write(struct rte_mbuf *pkt,
 			 uint32_t queue, enum rte_meter_color color);
 
 /**
- * Scheduler hierarchy path read from packet descriptor (struct rte_mbuf). Typically
- * called as part of the hierarchical scheduler enqueue operation. The subport,
- * pipe, traffic class and queue parameters need to be pre-allocated by the caller.
+ * Scheduler hierarchy path read from packet descriptor (struct
+ * rte_mbuf). Typically called as part of the hierarchical scheduler
+ * enqueue operation. The subport, pipe, traffic class and queue
+ * parameters need to be pre-allocated by the caller.
  *
  * @param pkt
  *   Packet descriptor handle
@@ -364,12 +400,13 @@ enum rte_meter_color
 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
 
 /**
- * Hierarchical scheduler port enqueue. Writes up to n_pkts to port scheduler and
- * returns the number of packets actually written. For each packet, the port scheduler
- * queue to write the packet to is identified by reading the hierarchy path from the
- * packet descriptor; if the queue is full or congested and the packet is not written
- * to the queue, then the packet is automatically dropped without any action required
- * from the caller.
+ * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
+ * scheduler and returns the number of packets actually written. For
+ * each packet, the port scheduler queue to write the packet to is
+ * identified by reading the hierarchy path from the packet
+ * descriptor; if the queue is full or congested and the packet is not
+ * written to the queue, then the packet is automatically dropped
+ * without any action required from the caller.
  *
  * @param port
  *   Handle to port scheduler instance
@@ -384,14 +421,16 @@ int
 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
 
 /**
- * Hierarchical scheduler port dequeue. Reads up to n_pkts from the port scheduler
- * and stores them in the pkts array and returns the number of packets actually read.
- * The pkts array needs to be pre-allocated by the caller with at least n_pkts entries.
+ * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
+ * port scheduler and stores them in the pkts array and returns the
+ * number of packets actually read.  The pkts array needs to be
+ * pre-allocated by the caller with at least n_pkts entries.
  *
  * @param port
  *   Handle to port scheduler instance
  * @param pkts
- *   Pre-allocated packet descriptor array where the packets dequeued from the port
+ *   Pre-allocated packet descriptor array where the packets dequeued
+ *   from the port
  *   scheduler should be stored
  * @param n_pkts
  *   Number of packets to dequeue from the port scheduler
-- 
2.1.4

  parent reply	other threads:[~2015-11-13 17:58 UTC|newest]

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-11-13 17:58 [dpdk-dev] [PATCH v2 00/10] rte_sched: enhancements and cleanups Stephen Hemminger
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 01/10] sched: drop deprecated port hierarchy structure Stephen Hemminger
2015-11-13 17:58 ` Stephen Hemminger [this message]
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 03/10] sched: make debugging configurable Stephen Hemminger
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 04/10] sched: drop debug #ifdef's for credit check Stephen Hemminger
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 05/10] sched: remove debug conditional code around ENQUEUE Stephen Hemminger
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 06/10] sched: drop RTE_SCHED_WRR #define Stephen Hemminger
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 07/10] sched: cleanup defined constants Stephen Hemminger
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 08/10] sched: allow enabling SSE optimizations in config Stephen Hemminger
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 09/10] sched: fix coding style Stephen Hemminger
2015-11-13 17:58 ` [dpdk-dev] [PATCH v2 10/10] sched: allow more subports Stephen Hemminger
2015-11-24 23:34 ` [dpdk-dev] [PATCH v2 00/10] rte_sched: enhancements and cleanups Thomas Monjalon

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1447437516-19152-3-git-send-email-stephen@networkplumber.org \
    --to=stephen@networkplumber.org \
    --cc=cristian.dumitrescu@intel.com \
    --cc=dev@dpdk.org \
    --cc=shemming@brocade.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).