From patchwork Fri Jul 19 14:18:20 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jasvinder Singh X-Patchwork-Id: 56791 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 8F88C1B998; Fri, 19 Jul 2019 16:18:37 +0200 (CEST) Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by dpdk.org (Postfix) with ESMTP id 375BC5680 for ; Fri, 19 Jul 2019 16:18:26 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga008.jf.intel.com ([10.7.209.65]) by orsmga102.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 19 Jul 2019 07:18:24 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.64,282,1559545200"; d="scan'208";a="162417202" Received: from silpixa00381635.ir.intel.com (HELO silpixa00381635.ger.corp.intel.com) ([10.237.223.4]) by orsmga008.jf.intel.com with ESMTP; 19 Jul 2019 07:18:24 -0700 From: Jasvinder Singh To: dev@dpdk.org Cc: cristian.dumitrescu@intel.com, Abraham Tovar , Lukasz Krakowiak Date: Fri, 19 Jul 2019 15:18:20 +0100 Message-Id: <20190719141825.101844-7-jasvinder.singh@intel.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190719141825.101844-1-jasvinder.singh@intel.com> References: <20190717144245.138876-2-jasvinder.singh@intel.com> <20190719141825.101844-1-jasvinder.singh@intel.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH v6 06/11] sched: improve doxygen comments X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Improve doxygen comments. Signed-off-by: Jasvinder Singh Signed-off-by: Abraham Tovar Signed-off-by: Lukasz Krakowiak --- lib/librte_sched/rte_sched.h | 152 ++++++++++++++++++++++------------- 1 file changed, 94 insertions(+), 58 deletions(-) diff --git a/lib/librte_sched/rte_sched.h b/lib/librte_sched/rte_sched.h index d7d4f1767..fffbad696 100644 --- a/lib/librte_sched/rte_sched.h +++ b/lib/librte_sched/rte_sched.h @@ -52,7 +52,7 @@ extern "C" { * 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. + * queues within same pipe lowest priority traffic class (best-effort). * */ @@ -83,7 +83,8 @@ extern "C" { #define RTE_SCHED_BE_QUEUES_PER_PIPE 4 /** Number of traffic classes per pipe (as well as subport). - * Cannot be changed. + * @see struct rte_sched_subport_params + * @see struct rte_sched_pipe_params */ #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE \ (RTE_SCHED_QUEUES_PER_PIPE - RTE_SCHED_BE_QUEUES_PER_PIPE + 1) @@ -113,6 +114,8 @@ extern "C" { * * The FCS is considered overhead only if not included in the packet * length (field pkt_len of struct rte_mbuf). + * + * @see struct rte_sched_port_params */ #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT 24 @@ -128,34 +131,36 @@ extern "C" { * byte. */ struct rte_sched_subport_params { - /* Subport token bucket */ - uint32_t tb_rate; /**< Rate (measured in bytes per second) */ - uint32_t tb_size; /**< Size (measured in credits) */ + /** Token bucket rate (measured in bytes per second) */ + uint32_t tb_rate; + + /** Token bucket size (measured in credits) */ + uint32_t tb_size; - /* Subport traffic classes */ + /** Traffic class rates (measured in bytes per second) */ uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; - /**< Traffic class rates (measured in bytes per second) */ + + /** Enforcement period for rates (measured in milliseconds) */ uint32_t tc_period; - /**< Enforcement period for rates (measured in milliseconds) */ }; /** Subport statistics */ struct rte_sched_subport_stats { - /* Packets */ + /** Number of packets successfully written */ uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; - /**< Number of packets successfully written */ + + /** Number of packets dropped */ uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; - /**< Number of packets dropped */ - /* Bytes */ + /** Number of bytes successfully written for each traffic class */ uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; - /**< Number of bytes successfully written for each traffic class */ + + /** Number of bytes dropped for each traffic class */ uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; - /**< Number of bytes dropped for each traffic class */ #ifdef RTE_SCHED_RED + /** Number of packets dropped by red */ uint32_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; - /**< Number of packets dropped by red */ #endif }; @@ -169,61 +174,90 @@ struct rte_sched_subport_stats { * byte. */ struct rte_sched_pipe_params { - /* Pipe token bucket */ - uint32_t tb_rate; /**< Rate (measured in bytes per second) */ - uint32_t tb_size; /**< Size (measured in credits) */ + /** Token bucket rate (measured in bytes per second) */ + uint32_t tb_rate; - /* Pipe traffic classes */ + /** Token bucket size (measured in credits) */ + uint32_t tb_size; + + /** Traffic class rates (measured in bytes per second) */ uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; - /**< Traffic class rates (measured in bytes per second) */ + + /** Enforcement period (measured in milliseconds) */ uint32_t tc_period; - /**< Enforcement period (measured in milliseconds) */ - uint8_t tc_ov_weight; /**< Weight Traffic class 3 oversubscription */ - /* Pipe queues */ - uint8_t wrr_weights[RTE_SCHED_BE_QUEUES_PER_PIPE]; /**< WRR weights */ + /** Best-effort traffic class oversubscription weight */ + uint8_t tc_ov_weight; + + /** WRR weights of best-effort traffic class queues */ + uint8_t wrr_weights[RTE_SCHED_BE_QUEUES_PER_PIPE]; }; /** Queue statistics */ struct rte_sched_queue_stats { - /* Packets */ - uint32_t n_pkts; /**< Packets successfully written */ - uint32_t n_pkts_dropped; /**< Packets dropped */ + /** Packets successfully written */ + uint32_t n_pkts; + + /** Packets dropped */ + uint32_t n_pkts_dropped; + #ifdef RTE_SCHED_RED - uint32_t n_pkts_red_dropped; /**< Packets dropped by RED */ + /** Packets dropped by RED */ + uint32_t n_pkts_red_dropped; #endif - /* Bytes */ - uint32_t n_bytes; /**< Bytes successfully written */ - uint32_t n_bytes_dropped; /**< Bytes dropped */ + /** Bytes successfully written */ + uint32_t n_bytes; + + /** Bytes dropped */ + uint32_t n_bytes_dropped; }; /** Port configuration parameters. */ struct rte_sched_port_params { - 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 */ + /** Name of the port to be associated */ + const char *name; + + /** CPU socket ID */ + int socket; + + /** Output port rate (measured in bytes per second) */ + uint32_t rate; + + /** Maximum Ethernet frame size (measured in bytes). + * Should not include the framing overhead. + */ + uint32_t mtu; + + /** Framing overhead per packet (measured in bytes) */ + uint32_t frame_overhead; + + /** Number of subports */ + uint32_t n_subports_per_port; + + /** Number of subport_pipes */ + uint32_t n_pipes_per_subport; + + /** Packet queue size for each traffic class. + * All the pipes within the same subport share the similar + * configuration for the queues. + */ 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. */ + + /** Pipe profile table. + * Every pipe is configured using one of the profiles from this table. + */ 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 */ + + /** Profiles in the pipe profile table */ + uint32_t n_pipe_profiles; + + /** Max profiles allowed in the pipe profile table */ uint32_t n_max_pipe_profiles; - /**< Max profiles allowed in the pipe profile table */ + #ifdef RTE_SCHED_RED - struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][RTE_COLORS]; /**< RED parameters */ + /** RED parameters */ + struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][RTE_COLORS]; #endif }; @@ -337,8 +371,9 @@ rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params); * Pointer to pre-allocated subport statistics structure where the statistics * counters should be stored * @param tc_ov - * Pointer to pre-allocated 4-entry array where the oversubscription status for - * each of the 4 subport traffic classes should be stored. + * Pointer to pre-allocated RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE-entry array + * where the oversubscription status for each of the subport traffic classes + * should be stored. * @return * 0 upon success, error code otherwise */ @@ -383,9 +418,10 @@ rte_sched_queue_read_stats(struct rte_sched_port *port, * @param pipe * Pipe ID within subport * @param traffic_class - * Traffic class ID within pipe (0 .. 3) + * Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE) * @param queue - * Queue ID within pipe traffic class (0 .. 3) + * Queue ID within pipe traffic class, 0 for high priority TCs, and + * 0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC * @param color * Packet color set */ @@ -410,10 +446,10 @@ rte_sched_port_pkt_write(struct rte_sched_port *port, * @param pipe * Pipe ID within subport * @param traffic_class - * Traffic class ID within pipe (0 .. 3) + * Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE) * @param queue - * Queue ID within pipe traffic class (0 .. 3) - * + * Queue ID within pipe traffic class, 0 for high priority TCs, and + * 0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC */ void rte_sched_port_pkt_read_tree_path(struct rte_sched_port *port,