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>
59 * Statistics counter type
61 enum rte_mtr_stats_type {
62 /** Number of packets passed as green by the policer. */
63 RTE_MTR_STATS_N_PKTS_GREEN = 1 << 0,
65 /** Number of packets passed as yellow by the policer. */
66 RTE_MTR_STATS_N_PKTS_YELLOW = 1 << 1,
68 /** Number of packets passed as red by the policer. */
69 RTE_MTR_STATS_N_PKTS_RED = 1 << 2,
71 /** Number of packets dropped by the policer. */
72 RTE_MTR_STATS_N_PKTS_DROPPED = 1 << 3,
74 /** Number of bytes passed as green by the policer. */
75 RTE_MTR_STATS_N_BYTES_GREEN = 1 << 4,
77 /** Number of bytes passed as yellow by the policer. */
78 RTE_MTR_STATS_N_BYTES_YELLOW = 1 << 5,
80 /** Number of bytes passed as red by the policer. */
81 RTE_MTR_STATS_N_BYTES_RED = 1 << 6,
83 /** Number of bytes dropped by the policer. */
84 RTE_MTR_STATS_N_BYTES_DROPPED = 1 << 7,
90 struct rte_mtr_stats {
91 /** Number of packets passed by the policer (per color). */
92 uint64_t n_pkts[RTE_COLORS];
94 /** Number of bytes passed by the policer (per color). */
95 uint64_t n_bytes[RTE_COLORS];
97 /** Number of packets dropped by the policer. */
98 uint64_t n_pkts_dropped;
100 /** Number of bytes passed by the policer. */
101 uint64_t n_bytes_dropped;
105 * Traffic metering algorithms
107 enum rte_mtr_algorithm {
108 /** No traffic metering performed, the output color is the same as the
109 * input color for every input packet. The meter of the MTR object is
110 * working in pass-through mode, having same effect as meter disable.
111 * @see rte_mtr_meter_disable()
115 /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
116 RTE_MTR_SRTCM_RFC2697,
118 /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
119 RTE_MTR_TRTCM_RFC2698,
121 /** Two Rate Three Color Marker (trTCM) - IETF RFC 4115. */
122 RTE_MTR_TRTCM_RFC4115,
128 struct rte_mtr_meter_profile {
129 /** Traffic metering algorithm. */
130 enum rte_mtr_algorithm alg;
134 /** Items only valid when *alg* is set to srTCM - RFC 2697. */
137 * Committed Information Rate (CIR)
138 * (bytes per second or packets per second).
142 /** Committed Burst Size (CBS) (bytes or packets). */
145 /** Excess Burst Size (EBS) (bytes or packets). */
149 /** Items only valid when *alg* is set to trTCM - RFC 2698. */
152 * Committed Information Rate (CIR)
153 * (bytes per second or packets per second).
158 * Peak Information Rate (PIR)
159 * (bytes per second or packets per second).
163 /** Committed Burst Size (CBS) (bytes or packets). */
166 /** Peak Burst Size (PBS) (bytes or packets). */
170 /** Items only valid when *alg* is set to trTCM - RFC 4115. */
173 * Committed Information Rate (CIR)
174 * (bytes per second or packets per second).
179 * Excess Information Rate (EIR)
180 * (bytes per second or packets per second).
184 /** Committed Burst Size (CBS) (bytes or packets). */
187 /** Excess Burst Size (EBS) (bytes or packets). */
193 * When zero, the byte mode is enabled for the current profile, so the
194 * *rate* and *size* fields are specified in bytes per second
195 * and bytes, respectively.
196 * When non-zero, the packet mode is enabled for the current profile,
197 * so the *rate* and *size* fields are specified in packets per second
198 * and packets, respectively.
206 struct rte_mtr_meter_policy_params {
208 * Policy action list per color.
209 * actions[i] potentially represents a chain of rte_flow actions
210 * terminated by the END action, exactly as specified by the rte_flow
211 * API for the flow definition, and not just a single action.
213 const struct rte_flow_action *actions[RTE_COLORS];
217 * Input color protocol method
219 * More than one of the method can be enabled for a given meter.
220 * Even if enabled, a method might not be applicable to each input packet,
221 * in case the associated protocol header is not present in the packet.
222 * The highest priority method that is both enabled for the meter and also
223 * applicable for the current input packet wins;
224 * if none is both enabled and applicable, the default input color is used.
225 * @see function rte_mtr_color_in_protocol_set()
228 enum rte_mtr_color_in_protocol {
230 * Enable the detection of the packet input color based on the outermost
231 * VLAN header fields DEI (1 bit) and PCP (3 bits).
232 * These fields are used as index into the VLAN table.
234 * @see struct rte_mtr_params::vlan_table
236 RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN = RTE_BIT64(0),
238 * Enable the detection of the packet input color based on the innermost
239 * VLAN header fields DEI (1 bit) and PCP (3 bits).
240 * These fields are used as index into the VLAN table.
242 * @see struct rte_mtr_params::vlan_table
244 RTE_MTR_COLOR_IN_PROTO_INNER_VLAN = RTE_BIT64(1),
246 * Enable the detection of the packet input color based on the outermost
247 * IP DSCP field. These fields are used as index into the DSCP table.
249 * @see struct rte_mtr_params::dscp_table
251 RTE_MTR_COLOR_IN_PROTO_OUTER_IP = RTE_BIT64(2),
253 * Enable the detection of the packet input color based on the innermost
254 * IP DSCP field. These fields are used as index into the DSCP table.
256 * @see struct rte_mtr_params::dscp_table
258 RTE_MTR_COLOR_IN_PROTO_INNER_IP = RTE_BIT64(3),
262 * Parameters for each traffic metering & policing object
264 * @see enum rte_mtr_stats_type
266 struct rte_mtr_params {
267 /** Meter profile ID. @see rte_mtr_meter_profile_add() */
268 uint32_t meter_profile_id;
270 /** Meter input color in case of MTR object chaining. When non-zero: if
271 * a previous MTR object is enabled in the same flow, then the color
272 * determined by the latest MTR object in the same flow is used as the
273 * input color by the current MTR object, otherwise the current MTR
274 * object uses the *dscp_table* to determine the input color. When zero:
275 * the color determined by any previous MTR object in same flow is
276 * ignored by the current MTR object, which uses the *dscp_table* to
277 * determine the input color.
279 int use_prev_mtr_color;
281 /** Meter input color based on IP DSCP protocol field.
283 * Valid when *input_color_proto_mask* set to any of the following
284 * RTE_MTR_COLOR_IN_PROTO_OUTER_IP,
285 * RTE_MTR_COLOR_IN_PROTO_INNER_IP
287 * When non-NULL: it points to a pre-allocated and
288 * pre-populated table with exactly 64 elements providing the input
289 * color for each value of the IPv4/IPv6 Differentiated Services Code
290 * Point (DSCP) input packet field.
292 * When NULL: it is equivalent to setting this parameter to an all-green
293 * populated table (i.e. table with all the 64 elements set to green
294 * color). The color blind mode is configured by setting
295 * *use_prev_mtr_color* to 0 and *dscp_table* to either NULL or to an
296 * all-green populated table.
298 * When *use_prev_mtr_color* is non-zero value or when *dscp_table*
299 * contains at least one yellow or red color element, then the color
300 * aware mode is configured.
302 * @see enum rte_mtr_color_in_protocol::RTE_MTR_COLOR_IN_PROTO_OUTER_IP
303 * @see enum rte_mtr_color_in_protocol::RTE_MTR_COLOR_IN_PROTO_INNER_IP
304 * @see struct rte_mtr_params::input_color_proto_mask
306 enum rte_color *dscp_table;
307 /** Meter input color based on VLAN DEI(1bit), PCP(3 bits) protocol
310 * Valid when *input_color_proto_mask* set to any of the following
311 * RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN,
312 * RTE_MTR_COLOR_IN_PROTO_INNER_VLAN
314 * When non-NULL: it points to a pre-allocated and pre-populated
315 * table with exactly 16 elements providing the input color for
316 * each value of the DEI(1bit), PCP(3 bits) input packet field.
318 * When NULL: it is equivalent to setting this parameter to an
319 * all-green populated table (i.e. table with
320 * all the 16 elements set to green color). The color blind mode
321 * is configured by setting *use_prev_mtr_color* to 0 and
322 * *vlan_table* to either NULL or to an all-green populated table.
324 * When *use_prev_mtr_color* is non-zero value
325 * or when *vlan_table* contains at least one yellow or
326 * red color element, then the color aware mode is configured.
328 * @see enum rte_mtr_color_in_protocol::RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN
329 * @see enum rte_mtr_color_in_protocol::RTE_MTR_COLOR_IN_PROTO_INNER_VLAN
330 * @see struct rte_mtr_params::input_color_proto_mask
332 enum rte_color *vlan_table;
333 /** Non-zero to enable the meter, zero to disable the meter at the time
334 * of MTR object creation. Ignored when the meter profile indicated by
335 * *meter_profile_id* is set to NONE.
336 * @see rte_mtr_meter_disable()
340 /** Set of stats counters to be enabled.
341 * @see enum rte_mtr_stats_type
345 /** Meter policy ID. @see rte_mtr_meter_policy_add() */
346 uint32_t meter_policy_id;
348 /** Input color to be set for the input packet when none of the
349 * enabled input color methods is applicable to the input packet.
350 * Ignored when this when *input_color_proto_mask* set to zero.
352 enum rte_color default_input_color;
358 struct rte_mtr_capabilities {
359 /** Maximum number of MTR objects. */
362 /** Maximum number of MTR objects that can be shared by multiple flows.
363 * The value of zero indicates that shared MTR objects are not
364 * supported. The maximum value is *n_max*.
366 uint32_t n_shared_max;
368 /** When non-zero, this flag indicates that all the MTR objects that
369 * cannot be shared by multiple flows have identical capability set.
373 /** When non-zero, this flag indicates that all the MTR objects that
374 * can be shared by multiple flows have identical capability set.
376 int shared_identical;
378 /** Maximum number of flows that can share the same MTR object. The
379 * value of zero is invalid. The value of 1 means that shared MTR
380 * objects not supported.
382 uint32_t shared_n_flows_per_mtr_max;
384 /** Maximum number of MTR objects that can be part of the same flow. The
385 * value of zero is invalid. The value of 1 indicates that MTR object
386 * chaining is not supported. The maximum value is *n_max*.
388 uint32_t chaining_n_mtrs_per_flow_max;
391 * When non-zero, it indicates that the packet color identified by one
392 * MTR object can be used as the packet input color by any subsequent
393 * MTR object from the same flow. When zero, it indicates that the color
394 * determined by one MTR object is always ignored by any subsequent MTR
395 * object from the same flow. Only valid when MTR chaining is supported,
396 * i.e. *chaining_n_mtrs_per_flow_max* is greater than 1. When non-zero,
397 * it also means that the color aware mode is supported by at least one
398 * metering algorithm.
400 int chaining_use_prev_mtr_color_supported;
403 * When non-zero, it indicates that the packet color identified by one
404 * MTR object is always used as the packet input color by any subsequent
405 * MTR object that is part of the same flow. When zero, it indicates
406 * that whether the color determined by one MTR object is either ignored
407 * or used as the packet input color by any subsequent MTR object from
408 * the same flow is individually configurable for each MTR object. Only
409 * valid when *chaining_use_prev_mtr_color_supported* is non-zero.
411 int chaining_use_prev_mtr_color_enforced;
413 /** Maximum number of MTR objects that can have their meter configured
414 * to run the srTCM RFC 2697 algorithm. The value of 0 indicates this
415 * metering algorithm is not supported. The maximum value is *n_max*.
417 uint32_t meter_srtcm_rfc2697_n_max;
419 /** Maximum number of MTR objects that can have their meter configured
420 * to run the trTCM RFC 2698 algorithm. The value of 0 indicates this
421 * metering algorithm is not supported. The maximum value is *n_max*.
423 uint32_t meter_trtcm_rfc2698_n_max;
425 /** Maximum number of MTR objects that can have their meter configured
426 * to run the trTCM RFC 4115 algorithm. The value of 0 indicates this
427 * metering algorithm is not supported. The maximum value is *n_max*.
429 uint32_t meter_trtcm_rfc4115_n_max;
431 /** Maximum traffic rate that can be metered by a single MTR object. For
432 * srTCM RFC 2697, this is the maximum CIR rate. For trTCM RFC 2698,
433 * this is the maximum PIR rate. For trTCM RFC 4115, this is the maximum
434 * value for the sum of PIR and EIR rates.
436 uint64_t meter_rate_max;
439 * Maximum number of policy objects that can have.
440 * The value of 0 is invalid. Policy must be supported for meter.
441 * The maximum value is *n_max*.
443 uint64_t meter_policy_n_max;
446 * When non-zero, it indicates that color aware mode is supported for
447 * the srTCM RFC 2697 metering algorithm.
449 int color_aware_srtcm_rfc2697_supported;
452 * When non-zero, it indicates that color aware mode is supported for
453 * the trTCM RFC 2698 metering algorithm.
455 int color_aware_trtcm_rfc2698_supported;
458 * When non-zero, it indicates that color aware mode is supported for
459 * the trTCM RFC 4115 metering algorithm.
461 int color_aware_trtcm_rfc4115_supported;
464 * srTCM rfc2697 byte mode supported.
465 * When non-zero, it indicates that byte mode is supported for
466 * the srTCM RFC 2697 metering algorithm.
468 int srtcm_rfc2697_byte_mode_supported;
471 * srTCM rfc2697 packet mode supported.
472 * When non-zero, it indicates that packet mode is supported for
473 * the srTCM RFC 2697 metering algorithm.
475 int srtcm_rfc2697_packet_mode_supported;
478 * trTCM rfc2698 byte mode supported.
479 * When non-zero, it indicates that byte mode is supported for
480 * the trTCM RFC 2698 metering algorithm.
482 int trtcm_rfc2698_byte_mode_supported;
485 * trTCM rfc2698 packet mode supported.
486 * When non-zero, it indicates that packet mode is supported for
487 * the trTCM RFC 2698 metering algorithm.
489 int trtcm_rfc2698_packet_mode_supported;
492 * trTCM rfc4115 byte mode supported.
493 * When non-zero, it indicates that byte mode is supported for
494 * the trTCM RFC 4115 metering algorithm.
496 int trtcm_rfc4115_byte_mode_supported;
499 * trTCM rfc4115 packet mode supported.
500 * When non-zero, it indicates that packet mode is supported for
501 * the trTCM RFC 4115 metering algorithm.
503 int trtcm_rfc4115_packet_mode_supported;
505 /** Set of supported statistics counter types.
506 * @see enum rte_mtr_stats_type
510 /** Set of supported input color protocol.
511 * @see enum rte_mtr_color_in_protocol
513 uint64_t input_color_proto_mask;
515 /** When non-zero, it indicates that driver supports separate
516 * input color table for given ethdev port.
518 int separate_input_color_table_per_port;
522 * Verbose error types.
524 * Most of them provide the type of the object referenced by struct
525 * rte_mtr_error::cause.
527 enum rte_mtr_error_type {
528 RTE_MTR_ERROR_TYPE_NONE, /**< No error. */
529 RTE_MTR_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
530 RTE_MTR_ERROR_TYPE_METER_PROFILE_ID,
531 RTE_MTR_ERROR_TYPE_METER_PROFILE,
532 RTE_MTR_ERROR_TYPE_METER_PROFILE_PACKET_MODE,
533 RTE_MTR_ERROR_TYPE_MTR_ID,
534 RTE_MTR_ERROR_TYPE_MTR_PARAMS,
535 RTE_MTR_ERROR_TYPE_POLICER_ACTION_GREEN,
536 RTE_MTR_ERROR_TYPE_POLICER_ACTION_YELLOW,
537 RTE_MTR_ERROR_TYPE_POLICER_ACTION_RED,
538 RTE_MTR_ERROR_TYPE_STATS_MASK,
539 RTE_MTR_ERROR_TYPE_STATS,
540 RTE_MTR_ERROR_TYPE_SHARED,
541 RTE_MTR_ERROR_TYPE_METER_POLICY_ID,
542 RTE_MTR_ERROR_TYPE_METER_POLICY,
546 * Verbose error structure definition.
548 * This object is normally allocated by applications and set by PMDs, the
549 * message points to a constant string which does not need to be freed by
550 * the application, however its pointer can be considered valid only as long
551 * as its associated DPDK port remains configured. Closing the underlying
552 * device or unloading the PMD invalidates it.
554 * Both cause and message may be NULL regardless of the error type.
556 struct rte_mtr_error {
557 enum rte_mtr_error_type type; /**< Cause field and error type. */
558 const void *cause; /**< Object responsible for the error. */
559 const char *message; /**< Human-readable error message. */
563 * MTR capabilities get
566 * The port identifier of the Ethernet device.
568 * MTR capabilities. Needs to be pre-allocated and valid.
570 * Error details. Filled in only on error, when not NULL.
572 * 0 on success, non-zero error code otherwise.
576 rte_mtr_capabilities_get(uint16_t port_id,
577 struct rte_mtr_capabilities *cap,
578 struct rte_mtr_error *error);
583 * Create a new meter profile with ID set to *meter_profile_id*. The new profile
584 * is used to create one or several MTR objects.
587 * The port identifier of the Ethernet device.
588 * @param[in] meter_profile_id
589 * ID for the new meter profile. Needs to be unused by any of the existing
590 * meter profiles added for the current port.
592 * Meter profile parameters. Needs to be pre-allocated and valid.
594 * Error details. Filled in only on error, when not NULL.
596 * 0 on success, non-zero error code otherwise.
600 rte_mtr_meter_profile_add(uint16_t port_id,
601 uint32_t meter_profile_id,
602 struct rte_mtr_meter_profile *profile,
603 struct rte_mtr_error *error);
606 * Meter profile delete
608 * Delete an existing meter profile. This operation fails when there is
609 * currently at least one user (i.e. MTR object) of this profile.
612 * The port identifier of the Ethernet device.
613 * @param[in] meter_profile_id
614 * Meter profile ID. Needs to be the valid.
616 * Error details. Filled in only on error, when not NULL.
618 * 0 on success, non-zero error code otherwise.
622 rte_mtr_meter_profile_delete(uint16_t port_id,
623 uint32_t meter_profile_id,
624 struct rte_mtr_error *error);
627 * Check whether a meter policy can be created on a given port.
629 * The meter policy is validated for correctness and
630 * whether it could be accepted by the device given sufficient resources.
631 * The policy is checked against the current capability information
632 * meter_policy_n_max configuration.
633 * The policy may also optionally be validated against existing
634 * device policy resources.
635 * This function has no effect on the target device.
638 * The port identifier of the Ethernet device.
640 * Associated action list per color.
641 * list NULL is legal and means no special action.
642 * (list terminated by the END action).
644 * Error details. Filled in only on error, when not NULL.
646 * 0 on success, non-zero error code otherwise.
650 rte_mtr_meter_policy_validate(uint16_t port_id,
651 struct rte_mtr_meter_policy_params *policy,
652 struct rte_mtr_error *error);
657 * Create a new meter policy. The new policy
658 * is used to create single or multiple MTR objects.
659 * The same policy can be used to create multiple MTR objects.
662 * The port identifier of the Ethernet device.
663 * @param[in] policy_id
664 * Policy identifier for the new meter policy.
666 * Associated actions per color.
667 * list NULL is legal and means no special action.
668 * Non-NULL list must be terminated.
669 * (list terminated by the END action).
671 * Error details. Filled in only on error, when not NULL.
673 * 0 on success, non-zero error code otherwise.
677 rte_mtr_meter_policy_add(uint16_t port_id,
679 struct rte_mtr_meter_policy_params *policy,
680 struct rte_mtr_error *error);
683 * Define meter policy action list:
684 * GREEN - GREEN, YELLOW - YELLOW, RED - RED
686 #define rte_mtr_policy_pass_color(policy) \
687 struct rte_mtr_meter_policy_params policy = \
689 .actions[RTE_COLOR_GREEN] = (struct rte_flow_action[]) { \
691 .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
692 .conf = &(struct rte_flow_action_meter_color) { \
693 .color = RTE_COLOR_GREEN, \
697 .type = RTE_FLOW_ACTION_TYPE_END, \
700 .actions[RTE_COLOR_YELLOW] = (struct rte_flow_action[]) { \
702 .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
703 .conf = &(struct rte_flow_action_meter_color) { \
704 .color = RTE_COLOR_YELLOW, \
708 .type = RTE_FLOW_ACTION_TYPE_END, \
711 .actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
713 .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
714 .conf = &(struct rte_flow_action_meter_color) { \
715 .color = RTE_COLOR_RED, \
719 .type = RTE_FLOW_ACTION_TYPE_END, \
725 * Define meter policy action list:
726 * GREEN - Do nothing, YELLOW - Do nothing, RED - DROP
728 #define rte_mtr_policy_drop_red(policy) \
729 struct rte_mtr_meter_policy_params policy = \
731 .actions[RTE_COLOR_GREEN] = NULL, \
732 .actions[RTE_COLOR_YELLOW] = NULL, \
733 .actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
735 .type = RTE_FLOW_ACTION_TYPE_DROP, \
738 .type = RTE_FLOW_ACTION_TYPE_END, \
744 * Meter policy delete
746 * Delete an existing meter policy. This operation fails when there is
747 * currently at least one user (i.e. MTR object) of this policy.
750 * The port identifier of the Ethernet device.
751 * @param[in] policy_id
754 * Error details. Filled in only on error, when not NULL.
756 * 0 on success, non-zero error code otherwise.
760 rte_mtr_meter_policy_delete(uint16_t port_id,
762 struct rte_mtr_error *error);
767 * Create a new MTR object for the current port. This object is run as part of
768 * associated flow action for traffic metering and policing.
771 * The port identifier of the Ethernet device.
773 * MTR object ID. Needs to be unused by any of the existing MTR objects.
774 * created for the current port.
776 * MTR object params. Needs to be pre-allocated and valid.
778 * Non-zero when this MTR object can be shared by multiple flows, zero when
779 * this MTR object can be used by a single flow.
781 * Error details. Filled in only on error, when not NULL.
783 * 0 on success, non-zero error code otherwise.
785 * @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
789 rte_mtr_create(uint16_t port_id,
791 struct rte_mtr_params *params,
793 struct rte_mtr_error *error);
798 * Delete an existing MTR object. This operation fails when there is currently
799 * at least one user (i.e. flow) of this MTR object.
802 * The port identifier of the Ethernet device.
804 * MTR object ID. Needs to be valid.
805 * created for the current port.
807 * Error details. Filled in only on error, when not NULL.
809 * 0 on success, non-zero error code otherwise.
813 rte_mtr_destroy(uint16_t port_id,
815 struct rte_mtr_error *error);
818 * MTR object meter disable
820 * Disable the meter of an existing MTR object. In disabled state, the meter of
821 * the current MTR object works in pass-through mode, meaning that for each
822 * input packet the meter output color is always the same as the input color. In
823 * particular, when the meter of the current MTR object is configured in color
824 * blind mode, the input color is always green, so the meter output color is
825 * also always green. Note that the policer and the statistics of the current
826 * MTR object are working as usual while the meter is disabled. No action is
827 * taken and this function returns successfully when the meter of the current
828 * MTR object is already disabled.
831 * The port identifier of the Ethernet device.
835 * Error details. Filled in only on error, when not NULL.
837 * 0 on success, non-zero error code otherwise.
841 rte_mtr_meter_disable(uint16_t port_id,
843 struct rte_mtr_error *error);
846 * MTR object meter enable
848 * Enable the meter of an existing MTR object. If the MTR object has its meter
849 * already enabled, then no action is taken and this function returns
853 * The port identifier of the Ethernet device.
857 * Error details. Filled in only on error, when not NULL.
859 * 0 on success, non-zero error code otherwise.
863 rte_mtr_meter_enable(uint16_t port_id,
865 struct rte_mtr_error *error);
868 * MTR object meter profile update
871 * The port identifier of the Ethernet device.
873 * MTR object ID. Needs to be valid.
874 * @param[in] meter_profile_id
875 * Meter profile ID for the current MTR object. Needs to be valid.
877 * Error details. Filled in only on error, when not NULL.
879 * 0 on success, non-zero error code otherwise.
883 rte_mtr_meter_profile_update(uint16_t port_id,
885 uint32_t meter_profile_id,
886 struct rte_mtr_error *error);
889 * MTR object meter policy update
892 * The port identifier of the Ethernet device.
894 * MTR object ID. Needs to be valid.
895 * @param[in] meter_policy_id
896 * Meter policy ID for the current MTR object. Needs to be valid.
898 * Error details. Filled in only on error, when not NULL.
900 * 0 on success, non-zero error code otherwise.
904 rte_mtr_meter_policy_update(uint16_t port_id,
906 uint32_t meter_policy_id,
907 struct rte_mtr_error *error);
910 * MTR object DSCP table update
913 * The port identifier of the Ethernet device.
915 * MTR object ID. Needs to be valid.
916 * @param[in] dscp_table
917 * When non-NULL: it points to a pre-allocated and pre-populated table with
918 * exactly 64 elements providing the input color for each value of the
919 * IPv4/IPv6 Differentiated Services Code Point (DSCP) input packet field.
920 * When NULL: it is equivalent to setting this parameter to an "all-green"
921 * populated table (i.e. table with all the 64 elements set to green color).
923 * Error details. Filled in only on error, when not NULL.
925 * 0 on success, non-zero error code otherwise.
929 rte_mtr_meter_dscp_table_update(uint16_t port_id,
931 enum rte_color *dscp_table,
932 struct rte_mtr_error *error);
935 * MTR object VLAN table update
938 * The port identifier of the Ethernet device.
940 * MTR object ID. Needs to be valid.
941 * @param[in] vlan_table
942 * When non-NULL: it points to a pre-allocated and pre-populated table with
943 * exactly 16 elements providing the input color for each value of the
944 * each value of the DEI(1bit), PCP(3 bits) input packet field.
945 * When NULL: it is equivalent to setting this parameter to an "all-green"
946 * populated table (i.e. table with all the 16 elements set to green color).
948 * Error details. Filled in only on error, when not NULL.
950 * 0 on success, non-zero error code otherwise.
954 rte_mtr_meter_vlan_table_update(uint16_t port_id, uint32_t mtr_id,
955 enum rte_color *vlan_table,
956 struct rte_mtr_error *error);
959 * Set the input color protocol for a given MTR object
961 * More than one of the method can be enabled for a given meter.
962 * Even if enabled, a method might not be applicable to each input packet,
963 * in case the associated protocol header is not present in the packet.
964 * The highest priority method that is both enabled for the meter and also
965 * applicable for the current input packet wins;
966 * if none is both enabled and applicable, the default input color is used.
969 * The port identifier of the Ethernet device.
971 * MTR object ID. Needs to be valid.
973 * Input color protocol.
974 * @param[in] priority
975 * Input color protocol priority. Value zero indicates
976 * the highest priority.
978 * Error details. Filled in only on error, when not NULL.
980 * 0 on success, non-zero error code otherwise.
984 rte_mtr_color_in_protocol_set(uint16_t port_id, uint32_t mtr_id,
985 enum rte_mtr_color_in_protocol proto, uint32_t priority,
986 struct rte_mtr_error *error);
989 * Get the input color protocol for a given MTR object
992 * The port identifier of the Ethernet device.
994 * MTR object ID. Needs to be valid.
995 * @param[out] proto_mask
996 * Selected input color protocols as bit mask.
998 * Error details. Filled in only on error, when not NULL.
1000 * 0 on success, non-zero error code otherwise.
1005 rte_mtr_color_in_protocol_get(uint16_t port_id, uint32_t mtr_id,
1006 uint64_t *proto_mask,
1007 struct rte_mtr_error *error);
1010 * Get the priority associated with input color protocol for a given MTR object
1012 * @param[in] port_id
1013 * The port identifier of the Ethernet device.
1015 * MTR object ID. Needs to be valid.
1017 * Input color protocol.
1018 * @param[out] priority
1019 * Input color protocol priority associated with proto.
1021 * Error details. Filled in only on error, when not NULL.
1023 * 0 on success, non-zero error code otherwise.
1027 rte_mtr_color_in_protocol_priority_get(uint16_t port_id, uint32_t mtr_id,
1028 enum rte_mtr_color_in_protocol proto, uint32_t *priority,
1029 struct rte_mtr_error *error);
1032 * MTR object enabled statistics counters update
1034 * @param[in] port_id
1035 * The port identifier of the Ethernet device.
1037 * MTR object ID. Needs to be valid.
1038 * @param[in] stats_mask
1039 * Mask of statistics counter types to be enabled for the current MTR object.
1040 * Any statistics counter type not included in this set is to be disabled for
1041 * the current MTR object.
1043 * Error details. Filled in only on error, when not NULL.
1045 * 0 on success, non-zero error code otherwise.
1047 * @see enum rte_mtr_stats_type
1051 rte_mtr_stats_update(uint16_t port_id,
1053 uint64_t stats_mask,
1054 struct rte_mtr_error *error);
1057 * MTR object statistics counters read
1059 * @param[in] port_id
1060 * The port identifier of the Ethernet device.
1062 * MTR object ID. Needs to be valid.
1064 * When non-NULL, it contains the current value for the statistics counters
1065 * enabled for the current MTR object.
1066 * @param[out] stats_mask
1067 * When non-NULL, it contains the mask of statistics counter types that are
1068 * currently enabled for this MTR object, indicating which of the counters
1069 * retrieved with the *stats* structure are valid.
1071 * When this parameter has a non-zero value, the statistics counters are
1072 * cleared (i.e. set to zero) immediately after they have been read,
1073 * otherwise the statistics counters are left untouched.
1075 * Error details. Filled in only on error, when not NULL.
1077 * 0 on success, non-zero error code otherwise.
1079 * @see enum rte_mtr_stats_type
1083 rte_mtr_stats_read(uint16_t port_id,
1085 struct rte_mtr_stats *stats,
1086 uint64_t *stats_mask,
1088 struct rte_mtr_error *error);
1094 #endif /* __INCLUDE_RTE_MTR_H__ */