Provided by: dpdk-doc_24.11.2-2_all 
NAME
rte_mtr.h
SYNOPSIS
#include <stdint.h>
#include <rte_compat.h>
#include <rte_common.h>
#include <rte_meter.h>
#include <rte_flow.h>
Data Structures
struct rte_mtr_stats
struct rte_mtr_meter_profile
struct rte_mtr_meter_policy_params
struct rte_mtr_params
struct rte_mtr_capabilities
struct rte_mtr_error
Macros
#define rte_mtr_policy_pass_color(policy)
#define rte_mtr_policy_drop_red(policy)
Enumerations
enum rte_mtr_stats_type { RTE_MTR_STATS_N_PKTS_GREEN = 1 << 0, RTE_MTR_STATS_N_PKTS_YELLOW = 1 << 1,
RTE_MTR_STATS_N_PKTS_RED = 1 << 2, RTE_MTR_STATS_N_PKTS_DROPPED = 1 << 3, RTE_MTR_STATS_N_BYTES_GREEN
= 1 << 4, RTE_MTR_STATS_N_BYTES_YELLOW = 1 << 5, RTE_MTR_STATS_N_BYTES_RED = 1 << 6,
RTE_MTR_STATS_N_BYTES_DROPPED = 1 << 7 }
enum rte_mtr_algorithm { RTE_MTR_NONE = 0, RTE_MTR_SRTCM_RFC2697, RTE_MTR_TRTCM_RFC2698,
RTE_MTR_TRTCM_RFC4115 }
enum rte_mtr_color_in_protocol { RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN = RTE_BIT64(0),
RTE_MTR_COLOR_IN_PROTO_INNER_VLAN = RTE_BIT64(1), RTE_MTR_COLOR_IN_PROTO_OUTER_IP = RTE_BIT64(2),
RTE_MTR_COLOR_IN_PROTO_INNER_IP = RTE_BIT64(3) }
enum rte_mtr_error_type { RTE_MTR_ERROR_TYPE_NONE, RTE_MTR_ERROR_TYPE_UNSPECIFIED,
RTE_MTR_ERROR_TYPE_METER_PROFILE_ID, RTE_MTR_ERROR_TYPE_METER_PROFILE,
RTE_MTR_ERROR_TYPE_METER_PROFILE_PACKET_MODE, RTE_MTR_ERROR_TYPE_MTR_ID,
RTE_MTR_ERROR_TYPE_MTR_PARAMS, RTE_MTR_ERROR_TYPE_POLICER_ACTION_GREEN,
RTE_MTR_ERROR_TYPE_POLICER_ACTION_YELLOW, RTE_MTR_ERROR_TYPE_POLICER_ACTION_RED,
RTE_MTR_ERROR_TYPE_STATS_MASK, RTE_MTR_ERROR_TYPE_STATS, RTE_MTR_ERROR_TYPE_SHARED,
RTE_MTR_ERROR_TYPE_METER_POLICY_ID, RTE_MTR_ERROR_TYPE_METER_POLICY }
Functions
__rte_experimental int rte_mtr_capabilities_get (uint16_t port_id, struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_profile_add (uint16_t port_id, uint32_t meter_profile_id, struct
rte_mtr_meter_profile *profile, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_profile_delete (uint16_t port_id, uint32_t meter_profile_id, struct
rte_mtr_error *error)
__rte_experimental struct rte_flow_meter_profile * rte_mtr_meter_profile_get (uint16_t port_id, uint32_t
meter_profile_id, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_policy_validate (uint16_t port_id, struct
rte_mtr_meter_policy_params *policy, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_policy_add (uint16_t port_id, uint32_t policy_id, struct
rte_mtr_meter_policy_params *policy, struct rte_mtr_error *error)
__rte_experimental struct rte_flow_meter_policy * rte_mtr_meter_policy_get (uint16_t port_id, uint32_t
policy_id, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_policy_delete (uint16_t port_id, uint32_t policy_id, struct
rte_mtr_error *error)
__rte_experimental int rte_mtr_create (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_params *params,
int shared, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_destroy (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_disable (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error
*error)
__rte_experimental int rte_mtr_meter_enable (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error
*error)
__rte_experimental int rte_mtr_meter_profile_update (uint16_t port_id, uint32_t mtr_id, uint32_t
meter_profile_id, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_policy_update (uint16_t port_id, uint32_t mtr_id, uint32_t
meter_policy_id, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_dscp_table_update (uint16_t port_id, uint32_t mtr_id, enum
rte_mtr_color_in_protocol proto, enum rte_color *dscp_table, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_meter_vlan_table_update (uint16_t port_id, uint32_t mtr_id, enum
rte_mtr_color_in_protocol proto, enum rte_color *vlan_table, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_color_in_protocol_set (uint16_t port_id, uint32_t mtr_id, enum
rte_mtr_color_in_protocol proto, uint32_t priority, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_color_in_protocol_get (uint16_t port_id, uint32_t mtr_id, uint64_t
*proto_mask, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_color_in_protocol_priority_get (uint16_t port_id, uint32_t mtr_id, enum
rte_mtr_color_in_protocol proto, uint32_t *priority, struct rte_mtr_error *error)
__rte_experimental int rte_mtr_stats_update (uint16_t port_id, uint32_t mtr_id, uint64_t stats_mask,
struct rte_mtr_error *error)
__rte_experimental int rte_mtr_stats_read (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_stats
*stats, uint64_t *stats_mask, int clear, struct rte_mtr_error *error)
Detailed Description
RTE Generic Traffic Metering and Policing API
This interface provides the ability to configure the traffic metering and policing (MTR) in a generic
way.
The processing done for each input packet hitting a MTR object is: A) Traffic metering: The packet is
assigned a color (the meter output color), based on the previous history of the flow reflected in the
current state of the MTR object, according to the specific traffic metering algorithm. The traffic
metering algorithm can typically work in color aware mode, in which case the input packet already has an
initial color (the input color), or in color blind mode, which is equivalent to considering all input
packets initially colored as green. B) Policing: There is a separate policer action configured for each
meter output color, which can: a) Drop the packet. b) Keep the same packet color: the policer output
color matches the meter output color (essentially a no-op action). c) Recolor the packet: the policer
output color is different than the meter output color. The policer output color is the output color of
the packet, which is set in the packet meta-data (i.e. struct rte_mbuf::sched::color). C) Statistics: The
set of counters maintained for each MTR object is configurable and subject to the implementation support.
This set includes the number of packets and bytes dropped or passed for each output color.
Once successfully created, an MTR object is linked to one or several flows through the meter action of
the flow API. A) Whether an MTR object is private to a flow or potentially shared by several flows has to
be specified at creation time. B) Several meter actions can be potentially registered for the same flow.
Warning
EXPERIMENTAL: this API may change without prior notice
Definition in file rte_mtr.h.
Macro Definition Documentation
#define rte_mtr_policy_pass_color(policy)
Define meter policy action list: GREEN - GREEN, YELLOW - YELLOW, RED - RED
Definition at line 724 of file rte_mtr.h.
#define rte_mtr_policy_drop_red(policy)
Value:.PP
struct rte_mtr_meter_policy_params policy = \
{ \
.actions[RTE_COLOR_GREEN] = NULL, \
.actions[RTE_COLOR_YELLOW] = NULL, \
.actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
{ \
.type = RTE_FLOW_ACTION_TYPE_DROP, \
}, \
{ \
.type = RTE_FLOW_ACTION_TYPE_END, \
}, \
}, \
}
Define meter policy action list: GREEN - Do nothing, YELLOW - Do nothing, RED - DROP
Definition at line 766 of file rte_mtr.h.
Enumeration Type Documentation
enum rte_mtr_stats_type
Statistics counter type
Enumerator
RTE_MTR_STATS_N_PKTS_GREEN
Number of packets passed as green by the policer.
RTE_MTR_STATS_N_PKTS_YELLOW
Number of packets passed as yellow by the policer.
RTE_MTR_STATS_N_PKTS_RED
Number of packets passed as red by the policer.
RTE_MTR_STATS_N_PKTS_DROPPED
Number of packets dropped by the policer.
RTE_MTR_STATS_N_BYTES_GREEN
Number of bytes passed as green by the policer.
RTE_MTR_STATS_N_BYTES_YELLOW
Number of bytes passed as yellow by the policer.
RTE_MTR_STATS_N_BYTES_RED
Number of bytes passed as red by the policer.
RTE_MTR_STATS_N_BYTES_DROPPED
Number of bytes dropped by the policer.
Definition at line 61 of file rte_mtr.h.
enum rte_mtr_algorithm
Traffic metering algorithms
Enumerator
RTE_MTR_NONE
No traffic metering performed, the output color is the same as the input color for every input
packet. The meter of the MTR object is working in pass-through mode, having same effect as meter
disable.
See also
rte_mtr_meter_disable()
RTE_MTR_SRTCM_RFC2697
Single Rate Three Color Marker (srTCM) - IETF RFC 2697.
RTE_MTR_TRTCM_RFC2698
Two Rate Three Color Marker (trTCM) - IETF RFC 2698.
RTE_MTR_TRTCM_RFC4115
Two Rate Three Color Marker (trTCM) - IETF RFC 4115.
Definition at line 107 of file rte_mtr.h.
enum rte_mtr_color_in_protocol
Input color protocol method
More than one of the method can be enabled for a given meter. Even if enabled, a method might not be
applicable to each input packet, in case the associated protocol header is not present in the packet. The
highest priority method that is both enabled for the meter and also applicable for the current input
packet wins; if none is both enabled and applicable, the default input color is used.
See also
function rte_mtr_color_in_protocol_set()
Enumerator
RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN
Enable the detection of the packet input color based on the outermost VLAN header fields DEI (1
bit) and PCP (3 bits). These fields are used as index into the VLAN table.
See also
struct rte_mtr_params::vlan_table
RTE_MTR_COLOR_IN_PROTO_INNER_VLAN
Enable the detection of the packet input color based on the innermost VLAN header fields DEI (1
bit) and PCP (3 bits). These fields are used as index into the VLAN table.
See also
struct rte_mtr_params::vlan_table
RTE_MTR_COLOR_IN_PROTO_OUTER_IP
Enable the detection of the packet input color based on the outermost IP DSCP field. These fields
are used as index into the DSCP table.
See also
struct rte_mtr_params::dscp_table
RTE_MTR_COLOR_IN_PROTO_INNER_IP
Enable the detection of the packet input color based on the innermost IP DSCP field. These fields
are used as index into the DSCP table.
See also
struct rte_mtr_params::dscp_table
Definition at line 226 of file rte_mtr.h.
enum rte_mtr_error_type
Verbose error types.
Most of them provide the type of the object referenced by struct rte_mtr_error::cause.
Enumerator
RTE_MTR_ERROR_TYPE_NONE
No error.
RTE_MTR_ERROR_TYPE_UNSPECIFIED
Cause unspecified.
Definition at line 525 of file rte_mtr.h.
Function Documentation
__rte_experimental int rte_mtr_capabilities_get (uint16_t port_id, struct rte_mtr_capabilities * cap, struct
rte_mtr_error * error)
MTR capabilities get
Parameters
port_id The port identifier of the Ethernet device.
cap MTR capabilities. Needs to be pre-allocated and valid.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_profile_add (uint16_t port_id, uint32_t meter_profile_id, struct
rte_mtr_meter_profile * profile, struct rte_mtr_error * error)
Meter profile add
Create a new meter profile with ID set to meter_profile_id. The new profile is used to create one or
several MTR objects.
Parameters
port_id The port identifier of the Ethernet device.
meter_profile_id ID for the new meter profile. Needs to be unused by any of the existing meter
profiles added for the current port.
profile Meter profile parameters. Needs to be pre-allocated and valid.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_profile_delete (uint16_t port_id, uint32_t meter_profile_id, struct
rte_mtr_error * error)
Meter profile delete
Delete an existing meter profile. This operation fails when there is currently at least one user (i.e.
MTR object) of this profile.
Parameters
port_id The port identifier of the Ethernet device.
meter_profile_id Meter profile ID. Needs to be the valid.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental struct rte_flow_meter_profile * rte_mtr_meter_profile_get (uint16_t port_id, uint32_t
meter_profile_id, struct rte_mtr_error * error)
Meter profile object get
Get meter profile object for a given meter profile ID.
Parameters
port_id The port identifier of the Ethernet device.
meter_profile_id Meter profile ID. Needs to be the valid.
error Error details. Filled in only on error, when not NULL.
Returns
A valid handle in case of success, NULL otherwise.
__rte_experimental int rte_mtr_meter_policy_validate (uint16_t port_id, struct rte_mtr_meter_policy_params *
policy, struct rte_mtr_error * error)
Check whether a meter policy can be created on a given port.
The meter policy is validated for correctness and whether it could be accepted by the device given
sufficient resources. The policy is checked against the current capability information meter_policy_n_max
configuration. The policy may also optionally be validated against existing device policy resources. This
function has no effect on the target device.
Parameters
port_id The port identifier of the Ethernet device.
policy Associated action list per color. list NULL is legal and means no special action. (list
terminated by the END action).
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_policy_add (uint16_t port_id, uint32_t policy_id, struct
rte_mtr_meter_policy_params * policy, struct rte_mtr_error * error)
Meter policy add
Create a new meter policy. The new policy is used to create single or multiple MTR objects. The same
policy can be used to create multiple MTR objects.
Parameters
port_id The port identifier of the Ethernet device.
policy_id Policy identifier for the new meter policy.
policy Associated actions per color. list NULL is legal and means no special action. Non-NULL list
must be terminated. (list terminated by the END action).
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental struct rte_flow_meter_policy * rte_mtr_meter_policy_get (uint16_t port_id, uint32_t
policy_id, struct rte_mtr_error * error)
Meter policy object get
Get meter policy object for a given meter policy ID.
Parameters
port_id The port identifier of the Ethernet device.
policy_id Meter policy ID. Needs to be the valid.
error Error details. Filled in only on error, when not NULL.
Returns
A valid handle in case of success, NULL otherwise.
__rte_experimental int rte_mtr_meter_policy_delete (uint16_t port_id, uint32_t policy_id, struct
rte_mtr_error * error)
Meter policy delete
Delete an existing meter policy. This operation fails when there is currently at least one user (i.e. MTR
object) of this policy.
Parameters
port_id The port identifier of the Ethernet device.
policy_id Policy identifier.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_create (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_params * params, int
shared, struct rte_mtr_error * error)
MTR object create
Create a new MTR object for the current port. This object is run as part of associated flow action for
traffic metering and policing.
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be unused by any of the existing MTR objects. created for the current
port.
params MTR object params. Needs to be pre-allocated and valid.
shared Non-zero when this MTR object can be shared by multiple flows, zero when this MTR object can
be used by a single flow.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
See also
enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
__rte_experimental int rte_mtr_destroy (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error * error)
MTR object destroy
Delete an existing MTR object. This operation fails when there is currently at least one user (i.e. flow)
of this MTR object.
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid. created for the current port.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_disable (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error *
error)
MTR object meter disable
Disable the meter of an existing MTR object. In disabled state, the meter of the current MTR object works
in pass-through mode, meaning that for each input packet the meter output color is always the same as the
input color. In particular, when the meter of the current MTR object is configured in color blind mode,
the input color is always green, so the meter output color is also always green. Note that the policer
and the statistics of the current MTR object are working as usual while the meter is disabled. No action
is taken and this function returns successfully when the meter of the current MTR object is already
disabled.
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_enable (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error * error)
MTR object meter enable
Enable the meter of an existing MTR object. If the MTR object has its meter already enabled, then no
action is taken and this function returns successfully.
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_profile_update (uint16_t port_id, uint32_t mtr_id, uint32_t
meter_profile_id, struct rte_mtr_error * error)
MTR object meter profile update
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
meter_profile_id Meter profile ID for the current MTR object. Needs to be valid.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_policy_update (uint16_t port_id, uint32_t mtr_id, uint32_t
meter_policy_id, struct rte_mtr_error * error)
MTR object meter policy update
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
meter_policy_id Meter policy ID for the current MTR object. Needs to be valid.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_dscp_table_update (uint16_t port_id, uint32_t mtr_id, enum
rte_mtr_color_in_protocol proto, enum rte_color * dscp_table, struct rte_mtr_error * error)
MTR object DSCP table update
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
proto Input color protocol.
dscp_table When non-NULL: it points to a pre-allocated and pre-populated table with exactly 64
elements providing the input color for each value of the IPv4/IPv6 Differentiated Services Code Point
(DSCP) input packet field. When NULL: it is equivalent to setting this parameter to an 'all-green'
populated table (i.e. table with all the 64 elements set to green color).
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_meter_vlan_table_update (uint16_t port_id, uint32_t mtr_id, enum
rte_mtr_color_in_protocol proto, enum rte_color * vlan_table, struct rte_mtr_error * error)
MTR object VLAN table update
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
proto Input color protocol.
vlan_table When non-NULL: it points to a pre-allocated and pre-populated table with exactly 16
elements providing the input color for each value of the each value of the DEI(1bit), PCP(3 bits)
input packet field. When NULL: it is equivalent to setting this parameter to an 'all-green' populated
table (i.e. table with all the 16 elements set to green color).
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_color_in_protocol_set (uint16_t port_id, uint32_t mtr_id, enum
rte_mtr_color_in_protocol proto, uint32_t priority, struct rte_mtr_error * error)
Set the input color protocol for a given MTR object
More than one of the method can be enabled for a given meter. Even if enabled, a method might not be
applicable to each input packet, in case the associated protocol header is not present in the packet. The
highest priority method that is both enabled for the meter and also applicable for the current input
packet wins; if none is both enabled and applicable, the default input color is used.
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
proto Input color protocol.
priority Input color protocol priority. Value zero indicates the highest priority.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_color_in_protocol_get (uint16_t port_id, uint32_t mtr_id, uint64_t *
proto_mask, struct rte_mtr_error * error)
Get the input color protocol for a given MTR object
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
proto_mask Selected input color protocols as bit mask.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_color_in_protocol_priority_get (uint16_t port_id, uint32_t mtr_id, enum
rte_mtr_color_in_protocol proto, uint32_t * priority, struct rte_mtr_error * error)
Get the priority associated with input color protocol for a given MTR object
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
proto Input color protocol.
priority Input color protocol priority associated with proto.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
__rte_experimental int rte_mtr_stats_update (uint16_t port_id, uint32_t mtr_id, uint64_t stats_mask, struct
rte_mtr_error * error)
MTR object enabled statistics counters update
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
stats_mask Mask of statistics counter types to be enabled for the current MTR object. Any statistics
counter type not included in this set is to be disabled for the current MTR object.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
See also
enum rte_mtr_stats_type
__rte_experimental int rte_mtr_stats_read (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_stats * stats,
uint64_t * stats_mask, int clear, struct rte_mtr_error * error)
MTR object statistics counters read
Parameters
port_id The port identifier of the Ethernet device.
mtr_id MTR object ID. Needs to be valid.
stats When non-NULL, it contains the current value for the statistics counters enabled for the
current MTR object.
stats_mask When non-NULL, it contains the mask of statistics counter types that are currently enabled
for this MTR object, indicating which of the counters retrieved with the stats structure are valid.
clear When this parameter has a non-zero value, the statistics counters are cleared (i.e. set to
zero) immediately after they have been read, otherwise the statistics counters are left untouched.
error Error details. Filled in only on error, when not NULL.
Returns
0 on success, non-zero error code otherwise.
See also
enum rte_mtr_stats_type
Author
Generated automatically by Doxygen for DPDK from the source code.
DPDK Version 24.11.2 rte_mtr.h(3)