-----Original Message----- > Date: Fri, 9 Jun 2017 17:51:15 +0100 > From: Cristian Dumitrescu <cristian.dumitre...@intel.com> > To: dev@dpdk.org > CC: tho...@monjalon.net, jerin.ja...@caviumnetworks.com, > balasubramanian.manoha...@cavium.com, hemant.agra...@nxp.com, > shreyansh.j...@nxp.com, jasvinder.si...@intel.com, wenzhuo...@intel.com > Subject: [PATCH v5 2/2] ethdev: add traffic management API > X-Mailer: git-send-email 2.7.4 > > This patch introduces the generic ethdev API for the traffic manager > capability, which includes: hierarchical scheduling, traffic shaping, > congestion management, packet marking. > > Main features: > - Exposed as ethdev plugin capability (similar to rte_flow) > - Capability query API per port, per level and per node > - Scheduling algorithms: Strict Priority (SP), Weighed Fair Queuing (WFQ) > - Traffic shaping: single/dual rate, private (per node) and shared (by > multiple nodes) shapers > - Congestion management for hierarchy leaf nodes: algorithms of tail drop, > head drop, WRED; private (per node) and shared (by multiple nodes) WRED > contexts > - Packet marking: IEEE 802.1q (VLAN DEI), IETF RFC 3168 (IPv4/IPv6 ECN for > TCP and SCTP), IETF RFC 2597 (IPv4 / IPv6 DSCP) > > Signed-off-by: Cristian Dumitrescu <cristian.dumitre...@intel.com> > Acked-by: Jerin Jacob <jerin.ja...@caviumnetworks.com> > Acked-by: Balasubramanian.Manoharan > <balasubramanian.manoha...@caviumnetworks.com> > Acked-by: Hemant Agrawal <hemant.agra...@nxp.com> > --- > Changes in v5: > - Implemented feedback from Jerin [8] > - Add level parameter to node add API function > - Doxygen: fixed comments applicable to field below/before > - Doxygen: added missing @see > - Doxygen: fixed hooks in doc/api/doxy-api-index.md > - Doxygen: fixed table rendering > - Added copyright on API header file from Cavium and NXP to > existing Intel copyright > - MANTAINERS: added next-tm tree > - Added V4 ACKs from Jerin, Bala and Hemant > > Changes in v4: > - Implemented feedback from Hemant [6] > - Capability API: Reworked the port, level and node capability API > data structure to remove confusion due to "summary across all > nodes" approach, which made it unclear whether a particular > capability is supported by all nodes or by at least one node. > - Capability API: Added flags for "all nodes have identical > capability set" > - Suspended state: documented the required behavior in Doxygen > description > - Implemented feedback from Jerin [7] > - Node add: added level parameter (see new API function: > rte_tm_node_add_check_level()) > - RTE_TM_ETH_FRAMING_OVERHEAD, RTE_TM_ETH_FRAMING_OVERHEAD_FCS: > documented their usage in their Doxygen description > - Capability API: for each function, mention the related > capability field (Doxygen @see) > - stats_mask, capability_mask: document the enum flags used to > build each mask (Doxygen @see) > - Rename rte_tm_get_leaf_nodes() to > rte_tm_get_number_of_leaf_nodes() > - Doxygen: add @param[in, out] to the description of all API funcs > - Doxygen: fix hooks in doc/api/doxy-api-index.md > - Rename rte_tm_hierarchy_set() to rte_tm_hierarchy_commit(), improved > Doxygen description > - Node add, node delete: improved Doxygen description > - Fixed incorrect design assumption that packet-based weight mode for WFQ > is identical to WRR. As result, removed all references to WRR support. > Renamed the "scheduling mode" node parameters to "wfq_weight_mode". > > Changes in v3: > - Implemented feedback from Jerin [5] > - Changed naming convention: scheddev -> tm > - Improvements on the capability API: > - Specification of marking capabilities per color > - WFQ/WRR groups: sp_n_children_max -> > wfq_wrr_n_children_per_group_max, added wfq_wrr_n_groups_max, > improved description of both, improved description of > wfq_wrr_weight_max > - Dynamic updates: added KEEP_LEVEL and CHANGE_LEVEL for parent > update > - Enforced/documented restrictions for root node (node_add() and > update()) > - Enforced/documented shaper profile restrictions on PIR: PIR != 0, > PIR >= CIR > - Turned repetitive code in rte_tm.c into macro > - Removed dependency on rte_red.h file (added RED params to rte_tm.h) > - Color: removed "e_" from color names enum > - Fixed small Doxygen style issues > > Changes in v2: > - Implemented feedback from Hemant [4] > - Improvements on the capability API > - Added capability API for hierarchy level > - Merged stats capability into the capability API > - Added dynamic updates > - Added non-leaf/leaf union to the node capability structure > - Renamed sp_priority_min to sp_n_priorities_max, added > clarifications > - Fixed description for sp_n_children_max > - Clarified and enforced rule on node ID range for leaf and non-leaf nodes > - Added API functions to get node type (i.e. leaf/non-leaf): > get_leaf_nodes(), node_type_get() > - Added clarification for the root node: its creation, parent, role > - Macro NODE_ID_NULL as root node's parent > - Description of the node_add() and node_parent_update() API funcs > - Added clarification for the first time add vs. subsequent updates rule > - Cleaned up the description for the node_add() function > - Statistics API improvements > - Merged stats capability into the capability API > - Added API function node_stats_update() > - Added more stats per packet color > - Added more error types > - Fixed small Doxygen style issues > > Changes in v1 (since RFC [1]): > - Implemented as ethdev plugin (similar to rte_flow) as opposed to more > monolithic additions to ethdev itself > - Implemented feedback from Jerin [2] and Hemant [3]. Implemented all the > suggested items with only one exception, see the long list below, > hopefully nothing was forgotten. > - The item not done (hopefully for a good reason): driver-generated > object IDs. IMO the choice to have application-generated object IDs > adds marginal complexity to the driver (search ID function > required), but it provides huge simplification for the application. > The app does not need to worry about building & managing tree-like > structure for storing driver-generated object IDs, the app can use > its own convention for node IDs depending on the specific hierarchy > that it needs. Trivial example: identify all level-2 nodes with IDs > like 100, 200, 300, … and the level-3 nodes based on their level-2 > parents: 110, 120, 130, 140, …, 210, 220, 230, 240, …, 310, 320, > 330, … and level-4 nodes based on their level-3 parents: 111, 112, > 113, 114, …, 121, 122, 123, 124, …). Moreover, see the change log > for the other related simplification that was implemented: leaf > nodes now have predefined IDs that are the same with their Ethernet > TX queue ID ( therefore no translation is required for leaf nodes). > - Capability API. Done per port and per node as well. > - Dual rate shapers > - Added configuration of private shaper (per node) directly from the > shaper profile as part of node API (no shaper ID needed for private > shapers), while the shared shapers are configured outside of the node > API using shaper profile and communicated to the node using shared > shaper ID. So there is no configuration overhead for shared shapers if > the app does not use any of them. > - Leaf nodes now have predefined IDs that are the same with their Ethernet > TX queue ID (therefore no translation is required for leaf nodes). This > is also used to differentiate between a leaf node and a non-leaf node. > - Domain-specific errors to give a precise indication of the error cause > (same as done by rte_flow) > - Packet marking API > - Packet length optional adjustment for shapers, positive (e.g. for adding > Ethernet framing overhead of 20 bytes) or negative (e.g. for rate > limiting based on IP packet bytes) > > [1] RFC: http://dpdk.org/ml/archives/dev/2016-November/050956.html > [2] Jerin’s feedback on RFC: > http://www.dpdk.org/ml/archives/dev/2017-January/054484.html > [3] Hemant’s feedback on RFC: > http://www.dpdk.org/ml/archives/dev/2017-January/054866.html > [4] Hemant's feedback on v1: > http://www.dpdk.org/ml/archives/dev/2017-February/058033.html > [5] Jerin's feedback on v1: > http://www.dpdk.org/ml/archives/dev/2017-March/058895.html > [6] Hemant's feedback on v3: > http://www.dpdk.org/ml/archives/dev/2017-March/062354.html > [7] Jerin's feedback on v3: > http://www.dpdk.org/ml/archives/dev/2017-April/063429.html > [8] Jerin's feedback on v4: > http://www.dpdk.org/ml/archives/dev/2017-May/066932.html > > > MAINTAINERS | 5 + > lib/librte_ether/Makefile | 5 +- > lib/librte_ether/rte_ether_version.map | 30 + > lib/librte_ether/rte_tm.c | 438 ++++++++ > lib/librte_ether/rte_tm.h | 1899 > ++++++++++++++++++++++++++++++++ > lib/librte_ether/rte_tm_driver.h | 366 ++++++ > 6 files changed, 2742 insertions(+), 1 deletion(-) > create mode 100644 lib/librte_ether/rte_tm.c > create mode 100644 lib/librte_ether/rte_tm.h > create mode 100644 lib/librte_ether/rte_tm_driver.h
Please update the the missing the doxygen hooks in doc/api/doxy-api-index.md. If it makes sense, then add (@see) for the exact capability field for following functions. rte_tm_node_wred_context_update rte_tm_node_shared_wred_context_update rte_tm_node_shaper_update rte_tm_node_shared_shaper_update
