4 * Copyright 2017 Intel Corporation
6 * Copyright 2017 Cavium
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * * Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 * * Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in
16 * the documentation and/or other materials provided with the
18 * * Neither the name of Intel Corporation nor the names of its
19 * contributors may be used to endorse or promote products derived
20 * from this software without specific prior written permission.
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 #ifndef __INCLUDE_RTE_MTR_H__
36 #define __INCLUDE_RTE_MTR_H__
40 * RTE Generic Traffic Metering and Policing API
42 * This interface provides the ability to configure the traffic metering and
43 * policing (MTR) in a generic way.
45 * The processing done for each input packet hitting a MTR object is:
46 * A) Traffic metering: The packet is assigned a color (the meter output
47 * color), based on the previous history of the flow reflected in the
48 * current state of the MTR object, according to the specific traffic
49 * metering algorithm. The traffic metering algorithm can typically work
50 * in color aware mode, in which case the input packet already has an
51 * initial color (the input color), or in color blind mode, which is
52 * equivalent to considering all input packets initially colored as green.
53 * B) Policing: There is a separate policer action configured for each meter
54 * output color, which can:
56 * b) Keep the same packet color: the policer output color matches the
57 * meter output color (essentially a no-op action).
58 * c) Recolor the packet: the policer output color is different than
59 * the meter output color.
60 * The policer output color is the output color of the packet, which is
61 * set in the packet meta-data (i.e. struct rte_mbuf::sched::color).
62 * C) Statistics: The set of counters maintained for each MTR object is
63 * configurable and subject to the implementation support. This set
64 * includes the number of packets and bytes dropped or passed for each
67 * Once successfully created, an MTR object is linked to one or several flows
68 * through the meter action of the flow API.
69 * A) Whether an MTR object is private to a flow or potentially shared by
70 * several flows has to be specified at creation time.
71 * B) Several meter actions can be potentially registered for the same flow.
74 * @b EXPERIMENTAL: this API may change without prior notice
77 #include <rte_compat.h>
78 #include <rte_common.h>
79 #include <rte_meter.h>
86 * Statistics counter type
88 enum rte_mtr_stats_type {
89 /** Number of packets passed as green by the policer. */
90 RTE_MTR_STATS_N_PKTS_GREEN = 1 << 0,
92 /** Number of packets passed as yellow by the policer. */
93 RTE_MTR_STATS_N_PKTS_YELLOW = 1 << 1,
95 /** Number of packets passed as red by the policer. */
96 RTE_MTR_STATS_N_PKTS_RED = 1 << 2,
98 /** Number of packets dropped by the policer. */
99 RTE_MTR_STATS_N_PKTS_DROPPED = 1 << 3,
101 /** Number of bytes passed as green by the policer. */
102 RTE_MTR_STATS_N_BYTES_GREEN = 1 << 4,
104 /** Number of bytes passed as yellow by the policer. */
105 RTE_MTR_STATS_N_BYTES_YELLOW = 1 << 5,
107 /** Number of bytes passed as red by the policer. */
108 RTE_MTR_STATS_N_BYTES_RED = 1 << 6,
110 /** Number of bytes dropped by the policer. */
111 RTE_MTR_STATS_N_BYTES_DROPPED = 1 << 7,
115 * Statistics counters
117 struct rte_mtr_stats {
118 /** Number of packets passed by the policer (per color). */
119 uint64_t n_pkts[RTE_COLORS];
121 /** Number of bytes passed by the policer (per color). */
122 uint64_t n_bytes[RTE_COLORS];
124 /** Number of packets dropped by the policer. */
125 uint64_t n_pkts_dropped;
127 /** Number of bytes passed by the policer. */
128 uint64_t n_bytes_dropped;
132 * Traffic metering algorithms
134 enum rte_mtr_algorithm {
135 /** No traffic metering performed, the output color is the same as the
136 * input color for every input packet. The meter of the MTR object is
137 * working in pass-through mode, having same effect as meter disable.
138 * @see rte_mtr_meter_disable()
142 /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
143 RTE_MTR_SRTCM_RFC2697,
145 /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
146 RTE_MTR_TRTCM_RFC2698,
148 /** Two Rate Three Color Marker (trTCM) - IETF RFC 4115. */
149 RTE_MTR_TRTCM_RFC4115,
155 struct rte_mtr_meter_profile {
156 /** Traffic metering algorithm. */
157 enum rte_mtr_algorithm alg;
161 /** Items only valid when *alg* is set to srTCM - RFC 2697. */
163 /** Committed Information Rate (CIR) (bytes/second). */
166 /** Committed Burst Size (CBS) (bytes). */
169 /** Excess Burst Size (EBS) (bytes). */
173 /** Items only valid when *alg* is set to trTCM - RFC 2698. */
175 /** Committed Information Rate (CIR) (bytes/second). */
178 /** Peak Information Rate (PIR) (bytes/second). */
181 /** Committed Burst Size (CBS) (byes). */
184 /** Peak Burst Size (PBS) (bytes). */
188 /** Items only valid when *alg* is set to trTCM - RFC 4115. */
190 /** Committed Information Rate (CIR) (bytes/second). */
193 /** Excess Information Rate (EIR) (bytes/second). */
196 /** Committed Burst Size (CBS) (byes). */
199 /** Excess Burst Size (EBS) (bytes). */
208 enum rte_mtr_policer_action {
209 /** Recolor the packet as green. */
210 MTR_POLICER_ACTION_COLOR_GREEN = 0,
212 /** Recolor the packet as yellow. */
213 MTR_POLICER_ACTION_COLOR_YELLOW,
215 /** Recolor the packet as red. */
216 MTR_POLICER_ACTION_COLOR_RED,
218 /** Drop the packet. */
219 MTR_POLICER_ACTION_DROP,
223 * Parameters for each traffic metering & policing object
225 * @see enum rte_mtr_stats_type
227 struct rte_mtr_params {
228 /** Meter profile ID. */
229 uint32_t meter_profile_id;
231 /** Meter input color in case of MTR object chaining. When non-zero: if
232 * a previous MTR object is enabled in the same flow, then the color
233 * determined by the latest MTR object in the same flow is used as the
234 * input color by the current MTR object, otherwise the current MTR
235 * object uses the *dscp_table* to determine the input color. When zero:
236 * the color determined by any previous MTR object in same flow is
237 * ignored by the current MTR object, which uses the *dscp_table* to
238 * determine the input color.
240 int use_prev_mtr_color;
242 /** Meter input color. When non-NULL: it points to a pre-allocated and
243 * pre-populated table with exactly 64 elements providing the input
244 * color for each value of the IPv4/IPv6 Differentiated Services Code
245 * Point (DSCP) input packet field. When NULL: it is equivalent to
246 * setting this parameter to an all-green populated table (i.e. table
247 * with all the 64 elements set to green color). The color blind mode
248 * is configured by setting *use_prev_mtr_color* to 0 and *dscp_table*
249 * to either NULL or to an all-green populated table. When
250 * *use_prev_mtr_color* is non-zero value or when *dscp_table* contains
251 * at least one yellow or red color element, then the color aware mode
254 enum rte_color *dscp_table;
256 /** Non-zero to enable the meter, zero to disable the meter at the time
257 * of MTR object creation. Ignored when the meter profile indicated by
258 * *meter_profile_id* is set to NONE.
259 * @see rte_mtr_meter_disable()
263 /** Policer actions (per meter output color). */
264 enum rte_mtr_policer_action action[RTE_COLORS];
266 /** Set of stats counters to be enabled.
267 * @see enum rte_mtr_stats_type
275 struct rte_mtr_capabilities {
276 /** Maximum number of MTR objects. */
279 /** Maximum number of MTR objects that can be shared by multiple flows.
280 * The value of zero indicates that shared MTR objects are not
281 * supported. The maximum value is *n_max*.
283 uint32_t n_shared_max;
285 /** When non-zero, this flag indicates that all the MTR objects that
286 * cannot be shared by multiple flows have identical capability set.
290 /** When non-zero, this flag indicates that all the MTR objects that
291 * can be shared by multiple flows have identical capability set.
293 int shared_identical;
295 /** Maximum number of flows that can share the same MTR object. The
296 * value of zero is invalid. The value of 1 means that shared MTR
297 * objects not supported.
299 uint32_t shared_n_flows_per_mtr_max;
301 /** Maximum number of MTR objects that can be part of the same flow. The
302 * value of zero is invalid. The value of 1 indicates that MTR object
303 * chaining is not supported. The maximum value is *n_max*.
305 uint32_t chaining_n_mtrs_per_flow_max;
308 * When non-zero, it indicates that the packet color identified by one
309 * MTR object can be used as the packet input color by any subsequent
310 * MTR object from the same flow. When zero, it indicates that the color
311 * determined by one MTR object is always ignored by any subsequent MTR
312 * object from the same flow. Only valid when MTR chaining is supported,
313 * i.e. *chaining_n_mtrs_per_flow_max* is greater than 1. When non-zero,
314 * it also means that the color aware mode is supported by at least one
315 * metering algorithm.
317 int chaining_use_prev_mtr_color_supported;
320 * When non-zero, it indicates that the packet color identified by one
321 * MTR object is always used as the packet input color by any subsequent
322 * MTR object that is part of the same flow. When zero, it indicates
323 * that whether the color determined by one MTR object is either ignored
324 * or used as the packet input color by any subsequent MTR object from
325 * the same flow is individually configurable for each MTR object. Only
326 * valid when *chaining_use_prev_mtr_color_supported* is non-zero.
328 int chaining_use_prev_mtr_color_enforced;
330 /** Maximum number of MTR objects that can have their meter configured
331 * to run the srTCM RFC 2697 algorithm. The value of 0 indicates this
332 * metering algorithm is not supported. The maximum value is *n_max*.
334 uint32_t meter_srtcm_rfc2697_n_max;
336 /** Maximum number of MTR objects that can have their meter configured
337 * to run the trTCM RFC 2698 algorithm. The value of 0 indicates this
338 * metering algorithm is not supported. The maximum value is *n_max*.
340 uint32_t meter_trtcm_rfc2698_n_max;
342 /** Maximum number of MTR objects that can have their meter configured
343 * to run the trTCM RFC 4115 algorithm. The value of 0 indicates this
344 * metering algorithm is not supported. The maximum value is *n_max*.
346 uint32_t meter_trtcm_rfc4115_n_max;
348 /** Maximum traffic rate that can be metered by a single MTR object. For
349 * srTCM RFC 2697, this is the maximum CIR rate. For trTCM RFC 2698,
350 * this is the maximum PIR rate. For trTCM RFC 4115, this is the maximum
351 * value for the sum of PIR and EIR rates.
353 uint64_t meter_rate_max;
356 * When non-zero, it indicates that color aware mode is supported for
357 * the srTCM RFC 2697 metering algorithm.
359 int color_aware_srtcm_rfc2697_supported;
362 * When non-zero, it indicates that color aware mode is supported for
363 * the trTCM RFC 2698 metering algorithm.
365 int color_aware_trtcm_rfc2698_supported;
368 * When non-zero, it indicates that color aware mode is supported for
369 * the trTCM RFC 4115 metering algorithm.
371 int color_aware_trtcm_rfc4115_supported;
373 /** When non-zero, it indicates that the policer packet recolor actions
375 * @see enum rte_mtr_policer_action
377 int policer_action_recolor_supported;
379 /** When non-zero, it indicates that the policer packet drop action is
381 * @see enum rte_mtr_policer_action
383 int policer_action_drop_supported;
385 /** Set of supported statistics counter types.
386 * @see enum rte_mtr_stats_type
392 * Verbose error types.
394 * Most of them provide the type of the object referenced by struct
395 * rte_mtr_error::cause.
397 enum rte_mtr_error_type {
398 RTE_MTR_ERROR_TYPE_NONE, /**< No error. */
399 RTE_MTR_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
400 RTE_MTR_ERROR_TYPE_METER_PROFILE_ID,
401 RTE_MTR_ERROR_TYPE_METER_PROFILE,
402 RTE_MTR_ERROR_TYPE_MTR_ID,
403 RTE_MTR_ERROR_TYPE_MTR_PARAMS,
404 RTE_MTR_ERROR_TYPE_POLICER_ACTION_GREEN,
405 RTE_MTR_ERROR_TYPE_POLICER_ACTION_YELLOW,
406 RTE_MTR_ERROR_TYPE_POLICER_ACTION_RED,
407 RTE_MTR_ERROR_TYPE_STATS_MASK,
408 RTE_MTR_ERROR_TYPE_STATS,
409 RTE_MTR_ERROR_TYPE_SHARED,
413 * Verbose error structure definition.
415 * This object is normally allocated by applications and set by PMDs, the
416 * message points to a constant string which does not need to be freed by
417 * the application, however its pointer can be considered valid only as long
418 * as its associated DPDK port remains configured. Closing the underlying
419 * device or unloading the PMD invalidates it.
421 * Both cause and message may be NULL regardless of the error type.
423 struct rte_mtr_error {
424 enum rte_mtr_error_type type; /**< Cause field and error type. */
425 const void *cause; /**< Object responsible for the error. */
426 const char *message; /**< Human-readable error message. */
430 * MTR capabilities get
433 * The port identifier of the Ethernet device.
435 * MTR capabilities. Needs to be pre-allocated and valid.
437 * Error details. Filled in only on error, when not NULL.
439 * 0 on success, non-zero error code otherwise.
441 int __rte_experimental
442 rte_mtr_capabilities_get(uint16_t port_id,
443 struct rte_mtr_capabilities *cap,
444 struct rte_mtr_error *error);
449 * Create a new meter profile with ID set to *meter_profile_id*. The new profile
450 * is used to create one or several MTR objects.
453 * The port identifier of the Ethernet device.
454 * @param[in] meter_profile_id
455 * ID for the new meter profile. Needs to be unused by any of the existing
456 * meter profiles added for the current port.
458 * Meter profile parameters. Needs to be pre-allocated and valid.
460 * Error details. Filled in only on error, when not NULL.
462 * 0 on success, non-zero error code otherwise.
464 int __rte_experimental
465 rte_mtr_meter_profile_add(uint16_t port_id,
466 uint32_t meter_profile_id,
467 struct rte_mtr_meter_profile *profile,
468 struct rte_mtr_error *error);
471 * Meter profile delete
473 * Delete an existing meter profile. This operation fails when there is
474 * currently at least one user (i.e. MTR object) of this profile.
477 * The port identifier of the Ethernet device.
478 * @param[in] meter_profile_id
479 * Meter profile ID. Needs to be the valid.
481 * Error details. Filled in only on error, when not NULL.
483 * 0 on success, non-zero error code otherwise.
485 int __rte_experimental
486 rte_mtr_meter_profile_delete(uint16_t port_id,
487 uint32_t meter_profile_id,
488 struct rte_mtr_error *error);
493 * Create a new MTR object for the current port. This object is run as part of
494 * associated flow action for traffic metering and policing.
497 * The port identifier of the Ethernet device.
499 * MTR object ID. Needs to be unused by any of the existing MTR objects.
500 * created for the current port.
502 * MTR object params. Needs to be pre-allocated and valid.
504 * Non-zero when this MTR object can be shared by multiple flows, zero when
505 * this MTR object can be used by a single flow.
507 * Error details. Filled in only on error, when not NULL.
509 * 0 on success, non-zero error code otherwise.
511 * @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
513 int __rte_experimental
514 rte_mtr_create(uint16_t port_id,
516 struct rte_mtr_params *params,
518 struct rte_mtr_error *error);
523 * Delete an existing MTR object. This operation fails when there is currently
524 * at least one user (i.e. flow) of this MTR object.
527 * The port identifier of the Ethernet device.
529 * MTR object ID. Needs to be valid.
530 * created for the current port.
532 * Error details. Filled in only on error, when not NULL.
534 * 0 on success, non-zero error code otherwise.
536 int __rte_experimental
537 rte_mtr_destroy(uint16_t port_id,
539 struct rte_mtr_error *error);
542 * MTR object meter disable
544 * Disable the meter of an existing MTR object. In disabled state, the meter of
545 * the current MTR object works in pass-through mode, meaning that for each
546 * input packet the meter output color is always the same as the input color. In
547 * particular, when the meter of the current MTR object is configured in color
548 * blind mode, the input color is always green, so the meter output color is
549 * also always green. Note that the policer and the statistics of the current
550 * MTR object are working as usual while the meter is disabled. No action is
551 * taken and this function returns successfully when the meter of the current
552 * MTR object is already disabled.
555 * The port identifier of the Ethernet device.
559 * Error details. Filled in only on error, when not NULL.
561 * 0 on success, non-zero error code otherwise.
563 int __rte_experimental
564 rte_mtr_meter_disable(uint16_t port_id,
566 struct rte_mtr_error *error);
569 * MTR object meter enable
571 * Enable the meter of an existing MTR object. If the MTR object has its meter
572 * already enabled, then no action is taken and this function returns
576 * The port identifier of the Ethernet device.
580 * Error details. Filled in only on error, when not NULL.
582 * 0 on success, non-zero error code otherwise.
584 int __rte_experimental
585 rte_mtr_meter_enable(uint16_t port_id,
587 struct rte_mtr_error *error);
590 * MTR object meter profile update
593 * The port identifier of the Ethernet device.
595 * MTR object ID. Needs to be valid.
596 * @param[in] meter_profile_id
597 * Meter profile ID for the current MTR object. Needs to be valid.
599 * Error details. Filled in only on error, when not NULL.
601 * 0 on success, non-zero error code otherwise.
603 int __rte_experimental
604 rte_mtr_meter_profile_update(uint16_t port_id,
606 uint32_t meter_profile_id,
607 struct rte_mtr_error *error);
610 * MTR object DSCP table update
613 * The port identifier of the Ethernet device.
615 * MTR object ID. Needs to be valid.
616 * @param[in] dscp_table
617 * When non-NULL: it points to a pre-allocated and pre-populated table with
618 * exactly 64 elements providing the input color for each value of the
619 * IPv4/IPv6 Differentiated Services Code Point (DSCP) input packet field.
620 * When NULL: it is equivalent to setting this parameter to an “all-green”
621 * populated table (i.e. table with all the 64 elements set to green color).
623 * Error details. Filled in only on error, when not NULL.
625 * 0 on success, non-zero error code otherwise.
627 int __rte_experimental
628 rte_mtr_meter_dscp_table_update(uint16_t port_id,
630 enum rte_color *dscp_table,
631 struct rte_mtr_error *error);
634 * MTR object policer actions update
637 * The port identifier of the Ethernet device.
639 * MTR object ID. Needs to be valid.
640 * @param[in] action_mask
641 * Bit mask indicating which policer actions need to be updated. One or more
642 * policer actions can be updated in a single function invocation. To update
643 * the policer action associated with color C, bit (1 << C) needs to be set in
644 * *action_mask* and element at position C in the *actions* array needs to be
647 * Pre-allocated and pre-populated array of policer actions.
649 * Error details. Filled in only on error, when not NULL.
651 * 0 on success, non-zero error code otherwise.
653 int __rte_experimental
654 rte_mtr_policer_actions_update(uint16_t port_id,
656 uint32_t action_mask,
657 enum rte_mtr_policer_action *actions,
658 struct rte_mtr_error *error);
661 * MTR object enabled statistics counters update
664 * The port identifier of the Ethernet device.
666 * MTR object ID. Needs to be valid.
667 * @param[in] stats_mask
668 * Mask of statistics counter types to be enabled for the current MTR object.
669 * Any statistics counter type not included in this set is to be disabled for
670 * the current MTR object.
672 * Error details. Filled in only on error, when not NULL.
674 * 0 on success, non-zero error code otherwise.
676 * @see enum rte_mtr_stats_type
678 int __rte_experimental
679 rte_mtr_stats_update(uint16_t port_id,
682 struct rte_mtr_error *error);
685 * MTR object statistics counters read
688 * The port identifier of the Ethernet device.
690 * MTR object ID. Needs to be valid.
692 * When non-NULL, it contains the current value for the statistics counters
693 * enabled for the current MTR object.
694 * @param[out] stats_mask
695 * When non-NULL, it contains the mask of statistics counter types that are
696 * currently enabled for this MTR object, indicating which of the counters
697 * retrieved with the *stats* structure are valid.
699 * When this parameter has a non-zero value, the statistics counters are
700 * cleared (i.e. set to zero) immediately after they have been read,
701 * otherwise the statistics counters are left untouched.
703 * Error details. Filled in only on error, when not NULL.
705 * 0 on success, non-zero error code otherwise.
707 * @see enum rte_mtr_stats_type
709 int __rte_experimental
710 rte_mtr_stats_read(uint16_t port_id,
712 struct rte_mtr_stats *stats,
713 uint64_t *stats_mask,
715 struct rte_mtr_error *error);
721 #endif /* __INCLUDE_RTE_MTR_H__ */