1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2017 Intel Corporation
4 * Copyright 2017 Cavium
7 #ifndef __INCLUDE_RTE_MTR_H__
8 #define __INCLUDE_RTE_MTR_H__
12 * RTE Generic Traffic Metering and Policing API
14 * This interface provides the ability to configure the traffic metering and
15 * policing (MTR) in a generic way.
17 * The processing done for each input packet hitting a MTR object is:
18 * A) Traffic metering: The packet is assigned a color (the meter output
19 * color), based on the previous history of the flow reflected in the
20 * current state of the MTR object, according to the specific traffic
21 * metering algorithm. The traffic metering algorithm can typically work
22 * in color aware mode, in which case the input packet already has an
23 * initial color (the input color), or in color blind mode, which is
24 * equivalent to considering all input packets initially colored as green.
25 * B) Policing: There is a separate policer action configured for each meter
26 * output color, which can:
28 * b) Keep the same packet color: the policer output color matches the
29 * meter output color (essentially a no-op action).
30 * c) Recolor the packet: the policer output color is different than
31 * the meter output color.
32 * The policer output color is the output color of the packet, which is
33 * set in the packet meta-data (i.e. struct rte_mbuf::sched::color).
34 * C) Statistics: The set of counters maintained for each MTR object is
35 * configurable and subject to the implementation support. This set
36 * includes the number of packets and bytes dropped or passed for each
39 * Once successfully created, an MTR object is linked to one or several flows
40 * through the meter action of the flow API.
41 * A) Whether an MTR object is private to a flow or potentially shared by
42 * several flows has to be specified at creation time.
43 * B) Several meter actions can be potentially registered for the same flow.
46 * @b EXPERIMENTAL: this API may change without prior notice
49 #include <rte_compat.h>
50 #include <rte_common.h>
51 #include <rte_meter.h>
58 * Statistics counter type
60 enum rte_mtr_stats_type {
61 /** Number of packets passed as green by the policer. */
62 RTE_MTR_STATS_N_PKTS_GREEN = 1 << 0,
64 /** Number of packets passed as yellow by the policer. */
65 RTE_MTR_STATS_N_PKTS_YELLOW = 1 << 1,
67 /** Number of packets passed as red by the policer. */
68 RTE_MTR_STATS_N_PKTS_RED = 1 << 2,
70 /** Number of packets dropped by the policer. */
71 RTE_MTR_STATS_N_PKTS_DROPPED = 1 << 3,
73 /** Number of bytes passed as green by the policer. */
74 RTE_MTR_STATS_N_BYTES_GREEN = 1 << 4,
76 /** Number of bytes passed as yellow by the policer. */
77 RTE_MTR_STATS_N_BYTES_YELLOW = 1 << 5,
79 /** Number of bytes passed as red by the policer. */
80 RTE_MTR_STATS_N_BYTES_RED = 1 << 6,
82 /** Number of bytes dropped by the policer. */
83 RTE_MTR_STATS_N_BYTES_DROPPED = 1 << 7,
89 struct rte_mtr_stats {
90 /** Number of packets passed by the policer (per color). */
91 uint64_t n_pkts[RTE_COLORS];
93 /** Number of bytes passed by the policer (per color). */
94 uint64_t n_bytes[RTE_COLORS];
96 /** Number of packets dropped by the policer. */
97 uint64_t n_pkts_dropped;
99 /** Number of bytes passed by the policer. */
100 uint64_t n_bytes_dropped;
104 * Traffic metering algorithms
106 enum rte_mtr_algorithm {
107 /** No traffic metering performed, the output color is the same as the
108 * input color for every input packet. The meter of the MTR object is
109 * working in pass-through mode, having same effect as meter disable.
110 * @see rte_mtr_meter_disable()
114 /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
115 RTE_MTR_SRTCM_RFC2697,
117 /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
118 RTE_MTR_TRTCM_RFC2698,
120 /** Two Rate Three Color Marker (trTCM) - IETF RFC 4115. */
121 RTE_MTR_TRTCM_RFC4115,
127 struct rte_mtr_meter_profile {
128 /** Traffic metering algorithm. */
129 enum rte_mtr_algorithm alg;
133 /** Items only valid when *alg* is set to srTCM - RFC 2697. */
136 * Committed Information Rate (CIR)
137 * (bytes per second or packets per second).
141 /** Committed Burst Size (CBS) (bytes or packets). */
144 /** Excess Burst Size (EBS) (bytes or packets). */
148 /** Items only valid when *alg* is set to trTCM - RFC 2698. */
151 * Committed Information Rate (CIR)
152 * (bytes per second or packets per second).
157 * Peak Information Rate (PIR)
158 * (bytes per second or packets per second).
162 /** Committed Burst Size (CBS) (bytes or packets). */
165 /** Peak Burst Size (PBS) (bytes or packets). */
169 /** Items only valid when *alg* is set to trTCM - RFC 4115. */
172 * Committed Information Rate (CIR)
173 * (bytes per second or packets per second).
178 * Excess Information Rate (EIR)
179 * (bytes per second or packets per second).
183 /** Committed Burst Size (CBS) (bytes or packets). */
186 /** Excess Burst Size (EBS) (bytes or packets). */
192 * When zero, the byte mode is enabled for the current profile, so the
193 * *rate* and *size* fields are specified in bytes per second
194 * and bytes, respectively.
195 * When non-zero, the packet mode is enabled for the current profile,
196 * so the *rate* and *size* fields are specified in packets per second
197 * and packets, respectively.
205 enum rte_mtr_policer_action {
206 /** Recolor the packet as green. */
207 MTR_POLICER_ACTION_COLOR_GREEN = 0,
209 /** Recolor the packet as yellow. */
210 MTR_POLICER_ACTION_COLOR_YELLOW,
212 /** Recolor the packet as red. */
213 MTR_POLICER_ACTION_COLOR_RED,
215 /** Drop the packet. */
216 MTR_POLICER_ACTION_DROP,
220 * Parameters for each traffic metering & policing object
222 * @see enum rte_mtr_stats_type
224 struct rte_mtr_params {
225 /** Meter profile ID. */
226 uint32_t meter_profile_id;
228 /** Meter input color in case of MTR object chaining. When non-zero: if
229 * a previous MTR object is enabled in the same flow, then the color
230 * determined by the latest MTR object in the same flow is used as the
231 * input color by the current MTR object, otherwise the current MTR
232 * object uses the *dscp_table* to determine the input color. When zero:
233 * the color determined by any previous MTR object in same flow is
234 * ignored by the current MTR object, which uses the *dscp_table* to
235 * determine the input color.
237 int use_prev_mtr_color;
239 /** Meter input color. When non-NULL: it points to a pre-allocated and
240 * pre-populated table with exactly 64 elements providing the input
241 * color for each value of the IPv4/IPv6 Differentiated Services Code
242 * Point (DSCP) input packet field. When NULL: it is equivalent to
243 * setting this parameter to an all-green populated table (i.e. table
244 * with all the 64 elements set to green color). The color blind mode
245 * is configured by setting *use_prev_mtr_color* to 0 and *dscp_table*
246 * to either NULL or to an all-green populated table. When
247 * *use_prev_mtr_color* is non-zero value or when *dscp_table* contains
248 * at least one yellow or red color element, then the color aware mode
251 enum rte_color *dscp_table;
253 /** Non-zero to enable the meter, zero to disable the meter at the time
254 * of MTR object creation. Ignored when the meter profile indicated by
255 * *meter_profile_id* is set to NONE.
256 * @see rte_mtr_meter_disable()
260 /** Policer actions (per meter output color). */
261 enum rte_mtr_policer_action action[RTE_COLORS];
263 /** Set of stats counters to be enabled.
264 * @see enum rte_mtr_stats_type
272 struct rte_mtr_capabilities {
273 /** Maximum number of MTR objects. */
276 /** Maximum number of MTR objects that can be shared by multiple flows.
277 * The value of zero indicates that shared MTR objects are not
278 * supported. The maximum value is *n_max*.
280 uint32_t n_shared_max;
282 /** When non-zero, this flag indicates that all the MTR objects that
283 * cannot be shared by multiple flows have identical capability set.
287 /** When non-zero, this flag indicates that all the MTR objects that
288 * can be shared by multiple flows have identical capability set.
290 int shared_identical;
292 /** Maximum number of flows that can share the same MTR object. The
293 * value of zero is invalid. The value of 1 means that shared MTR
294 * objects not supported.
296 uint32_t shared_n_flows_per_mtr_max;
298 /** Maximum number of MTR objects that can be part of the same flow. The
299 * value of zero is invalid. The value of 1 indicates that MTR object
300 * chaining is not supported. The maximum value is *n_max*.
302 uint32_t chaining_n_mtrs_per_flow_max;
305 * When non-zero, it indicates that the packet color identified by one
306 * MTR object can be used as the packet input color by any subsequent
307 * MTR object from the same flow. When zero, it indicates that the color
308 * determined by one MTR object is always ignored by any subsequent MTR
309 * object from the same flow. Only valid when MTR chaining is supported,
310 * i.e. *chaining_n_mtrs_per_flow_max* is greater than 1. When non-zero,
311 * it also means that the color aware mode is supported by at least one
312 * metering algorithm.
314 int chaining_use_prev_mtr_color_supported;
317 * When non-zero, it indicates that the packet color identified by one
318 * MTR object is always used as the packet input color by any subsequent
319 * MTR object that is part of the same flow. When zero, it indicates
320 * that whether the color determined by one MTR object is either ignored
321 * or used as the packet input color by any subsequent MTR object from
322 * the same flow is individually configurable for each MTR object. Only
323 * valid when *chaining_use_prev_mtr_color_supported* is non-zero.
325 int chaining_use_prev_mtr_color_enforced;
327 /** Maximum number of MTR objects that can have their meter configured
328 * to run the srTCM RFC 2697 algorithm. The value of 0 indicates this
329 * metering algorithm is not supported. The maximum value is *n_max*.
331 uint32_t meter_srtcm_rfc2697_n_max;
333 /** Maximum number of MTR objects that can have their meter configured
334 * to run the trTCM RFC 2698 algorithm. The value of 0 indicates this
335 * metering algorithm is not supported. The maximum value is *n_max*.
337 uint32_t meter_trtcm_rfc2698_n_max;
339 /** Maximum number of MTR objects that can have their meter configured
340 * to run the trTCM RFC 4115 algorithm. The value of 0 indicates this
341 * metering algorithm is not supported. The maximum value is *n_max*.
343 uint32_t meter_trtcm_rfc4115_n_max;
345 /** Maximum traffic rate that can be metered by a single MTR object. For
346 * srTCM RFC 2697, this is the maximum CIR rate. For trTCM RFC 2698,
347 * this is the maximum PIR rate. For trTCM RFC 4115, this is the maximum
348 * value for the sum of PIR and EIR rates.
350 uint64_t meter_rate_max;
353 * When non-zero, it indicates that color aware mode is supported for
354 * the srTCM RFC 2697 metering algorithm.
356 int color_aware_srtcm_rfc2697_supported;
359 * When non-zero, it indicates that color aware mode is supported for
360 * the trTCM RFC 2698 metering algorithm.
362 int color_aware_trtcm_rfc2698_supported;
365 * When non-zero, it indicates that color aware mode is supported for
366 * the trTCM RFC 4115 metering algorithm.
368 int color_aware_trtcm_rfc4115_supported;
370 /** When non-zero, it indicates that the policer packet recolor actions
372 * @see enum rte_mtr_policer_action
374 int policer_action_recolor_supported;
376 /** When non-zero, it indicates that the policer packet drop action is
378 * @see enum rte_mtr_policer_action
380 int policer_action_drop_supported;
383 * srTCM rfc2697 byte mode supported.
384 * When non-zero, it indicates that byte mode is supported for
385 * the srTCM RFC 2697 metering algorithm.
387 int srtcm_rfc2697_byte_mode_supported;
390 * srTCM rfc2697 packet mode supported.
391 * When non-zero, it indicates that packet mode is supported for
392 * the srTCM RFC 2697 metering algorithm.
394 int srtcm_rfc2697_packet_mode_supported;
397 * trTCM rfc2698 byte mode supported.
398 * When non-zero, it indicates that byte mode is supported for
399 * the trTCM RFC 2698 metering algorithm.
401 int trtcm_rfc2698_byte_mode_supported;
404 * trTCM rfc2698 packet mode supported.
405 * When non-zero, it indicates that packet mode is supported for
406 * the trTCM RFC 2698 metering algorithm.
408 int trtcm_rfc2698_packet_mode_supported;
411 * trTCM rfc4115 byte mode supported.
412 * When non-zero, it indicates that byte mode is supported for
413 * the trTCM RFC 4115 metering algorithm.
415 int trtcm_rfc4115_byte_mode_supported;
418 * trTCM rfc4115 packet mode supported.
419 * When non-zero, it indicates that packet mode is supported for
420 * the trTCM RFC 4115 metering algorithm.
422 int trtcm_rfc4115_packet_mode_supported;
424 /** Set of supported statistics counter types.
425 * @see enum rte_mtr_stats_type
431 * Verbose error types.
433 * Most of them provide the type of the object referenced by struct
434 * rte_mtr_error::cause.
436 enum rte_mtr_error_type {
437 RTE_MTR_ERROR_TYPE_NONE, /**< No error. */
438 RTE_MTR_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
439 RTE_MTR_ERROR_TYPE_METER_PROFILE_ID,
440 RTE_MTR_ERROR_TYPE_METER_PROFILE,
441 RTE_MTR_ERROR_TYPE_METER_PROFILE_PACKET_MODE,
442 RTE_MTR_ERROR_TYPE_MTR_ID,
443 RTE_MTR_ERROR_TYPE_MTR_PARAMS,
444 RTE_MTR_ERROR_TYPE_POLICER_ACTION_GREEN,
445 RTE_MTR_ERROR_TYPE_POLICER_ACTION_YELLOW,
446 RTE_MTR_ERROR_TYPE_POLICER_ACTION_RED,
447 RTE_MTR_ERROR_TYPE_STATS_MASK,
448 RTE_MTR_ERROR_TYPE_STATS,
449 RTE_MTR_ERROR_TYPE_SHARED,
453 * Verbose error structure definition.
455 * This object is normally allocated by applications and set by PMDs, the
456 * message points to a constant string which does not need to be freed by
457 * the application, however its pointer can be considered valid only as long
458 * as its associated DPDK port remains configured. Closing the underlying
459 * device or unloading the PMD invalidates it.
461 * Both cause and message may be NULL regardless of the error type.
463 struct rte_mtr_error {
464 enum rte_mtr_error_type type; /**< Cause field and error type. */
465 const void *cause; /**< Object responsible for the error. */
466 const char *message; /**< Human-readable error message. */
470 * MTR capabilities get
473 * The port identifier of the Ethernet device.
475 * MTR capabilities. Needs to be pre-allocated and valid.
477 * Error details. Filled in only on error, when not NULL.
479 * 0 on success, non-zero error code otherwise.
483 rte_mtr_capabilities_get(uint16_t port_id,
484 struct rte_mtr_capabilities *cap,
485 struct rte_mtr_error *error);
490 * Create a new meter profile with ID set to *meter_profile_id*. The new profile
491 * is used to create one or several MTR objects.
494 * The port identifier of the Ethernet device.
495 * @param[in] meter_profile_id
496 * ID for the new meter profile. Needs to be unused by any of the existing
497 * meter profiles added for the current port.
499 * Meter profile parameters. Needs to be pre-allocated and valid.
501 * Error details. Filled in only on error, when not NULL.
503 * 0 on success, non-zero error code otherwise.
507 rte_mtr_meter_profile_add(uint16_t port_id,
508 uint32_t meter_profile_id,
509 struct rte_mtr_meter_profile *profile,
510 struct rte_mtr_error *error);
513 * Meter profile delete
515 * Delete an existing meter profile. This operation fails when there is
516 * currently at least one user (i.e. MTR object) of this profile.
519 * The port identifier of the Ethernet device.
520 * @param[in] meter_profile_id
521 * Meter profile ID. Needs to be the valid.
523 * Error details. Filled in only on error, when not NULL.
525 * 0 on success, non-zero error code otherwise.
529 rte_mtr_meter_profile_delete(uint16_t port_id,
530 uint32_t meter_profile_id,
531 struct rte_mtr_error *error);
536 * Create a new MTR object for the current port. This object is run as part of
537 * associated flow action for traffic metering and policing.
540 * The port identifier of the Ethernet device.
542 * MTR object ID. Needs to be unused by any of the existing MTR objects.
543 * created for the current port.
545 * MTR object params. Needs to be pre-allocated and valid.
547 * Non-zero when this MTR object can be shared by multiple flows, zero when
548 * this MTR object can be used by a single flow.
550 * Error details. Filled in only on error, when not NULL.
552 * 0 on success, non-zero error code otherwise.
554 * @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
558 rte_mtr_create(uint16_t port_id,
560 struct rte_mtr_params *params,
562 struct rte_mtr_error *error);
567 * Delete an existing MTR object. This operation fails when there is currently
568 * at least one user (i.e. flow) of this MTR object.
571 * The port identifier of the Ethernet device.
573 * MTR object ID. Needs to be valid.
574 * created for the current port.
576 * Error details. Filled in only on error, when not NULL.
578 * 0 on success, non-zero error code otherwise.
582 rte_mtr_destroy(uint16_t port_id,
584 struct rte_mtr_error *error);
587 * MTR object meter disable
589 * Disable the meter of an existing MTR object. In disabled state, the meter of
590 * the current MTR object works in pass-through mode, meaning that for each
591 * input packet the meter output color is always the same as the input color. In
592 * particular, when the meter of the current MTR object is configured in color
593 * blind mode, the input color is always green, so the meter output color is
594 * also always green. Note that the policer and the statistics of the current
595 * MTR object are working as usual while the meter is disabled. No action is
596 * taken and this function returns successfully when the meter of the current
597 * MTR object is already disabled.
600 * The port identifier of the Ethernet device.
604 * Error details. Filled in only on error, when not NULL.
606 * 0 on success, non-zero error code otherwise.
610 rte_mtr_meter_disable(uint16_t port_id,
612 struct rte_mtr_error *error);
615 * MTR object meter enable
617 * Enable the meter of an existing MTR object. If the MTR object has its meter
618 * already enabled, then no action is taken and this function returns
622 * The port identifier of the Ethernet device.
626 * Error details. Filled in only on error, when not NULL.
628 * 0 on success, non-zero error code otherwise.
632 rte_mtr_meter_enable(uint16_t port_id,
634 struct rte_mtr_error *error);
637 * MTR object meter profile update
640 * The port identifier of the Ethernet device.
642 * MTR object ID. Needs to be valid.
643 * @param[in] meter_profile_id
644 * Meter profile ID for the current MTR object. Needs to be valid.
646 * Error details. Filled in only on error, when not NULL.
648 * 0 on success, non-zero error code otherwise.
652 rte_mtr_meter_profile_update(uint16_t port_id,
654 uint32_t meter_profile_id,
655 struct rte_mtr_error *error);
658 * MTR object DSCP table update
661 * The port identifier of the Ethernet device.
663 * MTR object ID. Needs to be valid.
664 * @param[in] dscp_table
665 * When non-NULL: it points to a pre-allocated and pre-populated table with
666 * exactly 64 elements providing the input color for each value of the
667 * IPv4/IPv6 Differentiated Services Code Point (DSCP) input packet field.
668 * When NULL: it is equivalent to setting this parameter to an “all-green”
669 * populated table (i.e. table with all the 64 elements set to green color).
671 * Error details. Filled in only on error, when not NULL.
673 * 0 on success, non-zero error code otherwise.
677 rte_mtr_meter_dscp_table_update(uint16_t port_id,
679 enum rte_color *dscp_table,
680 struct rte_mtr_error *error);
683 * MTR object policer actions update
686 * The port identifier of the Ethernet device.
688 * MTR object ID. Needs to be valid.
689 * @param[in] action_mask
690 * Bit mask indicating which policer actions need to be updated. One or more
691 * policer actions can be updated in a single function invocation. To update
692 * the policer action associated with color C, bit (1 << C) needs to be set in
693 * *action_mask* and element at position C in the *actions* array needs to be
696 * Pre-allocated and pre-populated array of policer actions.
698 * Error details. Filled in only on error, when not NULL.
700 * 0 on success, non-zero error code otherwise.
704 rte_mtr_policer_actions_update(uint16_t port_id,
706 uint32_t action_mask,
707 enum rte_mtr_policer_action *actions,
708 struct rte_mtr_error *error);
711 * MTR object enabled statistics counters update
714 * The port identifier of the Ethernet device.
716 * MTR object ID. Needs to be valid.
717 * @param[in] stats_mask
718 * Mask of statistics counter types to be enabled for the current MTR object.
719 * Any statistics counter type not included in this set is to be disabled for
720 * the current MTR object.
722 * Error details. Filled in only on error, when not NULL.
724 * 0 on success, non-zero error code otherwise.
726 * @see enum rte_mtr_stats_type
730 rte_mtr_stats_update(uint16_t port_id,
733 struct rte_mtr_error *error);
736 * MTR object statistics counters read
739 * The port identifier of the Ethernet device.
741 * MTR object ID. Needs to be valid.
743 * When non-NULL, it contains the current value for the statistics counters
744 * enabled for the current MTR object.
745 * @param[out] stats_mask
746 * When non-NULL, it contains the mask of statistics counter types that are
747 * currently enabled for this MTR object, indicating which of the counters
748 * retrieved with the *stats* structure are valid.
750 * When this parameter has a non-zero value, the statistics counters are
751 * cleared (i.e. set to zero) immediately after they have been read,
752 * otherwise the statistics counters are left untouched.
754 * Error details. Filled in only on error, when not NULL.
756 * 0 on success, non-zero error code otherwise.
758 * @see enum rte_mtr_stats_type
762 rte_mtr_stats_read(uint16_t port_id,
764 struct rte_mtr_stats *stats,
765 uint64_t *stats_mask,
767 struct rte_mtr_error *error);
773 #endif /* __INCLUDE_RTE_MTR_H__ */