#include <stdint.h>
#include <rte_compat.h>
#include <rte_common.h>
#include <rte_meter.h>

Data Structures
struct	rte_mtr_stats

struct	rte_mtr_meter_profile

struct	rte_mtr_params

struct	rte_mtr_capabilities

struct	rte_mtr_error

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_policer_action { MTR_POLICER_ACTION_COLOR_GREEN = 0, MTR_POLICER_ACTION_COLOR_YELLOW, MTR_POLICER_ACTION_COLOR_RED, MTR_POLICER_ACTION_DROP }

enum	rte_mtr_error_type { RTE_MTR_ERROR_TYPE_NONE, RTE_MTR_ERROR_TYPE_UNSPECIFIED }

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 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_dscp_table_update (uint16_t port_id, uint32_t mtr_id, enum rte_color dscp_table, struct rte_mtr_error error)

__rte_experimental int	rte_mtr_policer_actions_update (uint16_t port_id, uint32_t mtr_id, uint32_t action_mask, enum rte_mtr_policer_action actions, 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.

Enumeration Type Documentation

◆ rte_mtr_stats_type

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 60 of file rte_mtr.h.

◆ rte_mtr_algorithm

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 106 of file rte_mtr.h.

◆ rte_mtr_policer_action

enum rte_mtr_policer_action

Policer actions

Enumerator
MTR_POLICER_ACTION_COLOR_GREEN	Recolor the packet as green.
MTR_POLICER_ACTION_COLOR_YELLOW	Recolor the packet as yellow.
MTR_POLICER_ACTION_COLOR_RED	Recolor the packet as red.
MTR_POLICER_ACTION_DROP	Drop the packet.

Definition at line 180 of file rte_mtr.h.

◆ rte_mtr_error_type

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 369 of file rte_mtr.h.

Function Documentation

◆ rte_mtr_capabilities_get()

__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

[in]	port_id	The port identifier of the Ethernet device.
[out]	cap	MTR capabilities. Needs to be pre-allocated and valid.
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_meter_profile_add()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	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.
[in]	profile	Meter profile parameters. Needs to be pre-allocated and valid.
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_meter_profile_delete()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	meter_profile_id	Meter profile ID. Needs to be the valid.
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_create()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID. Needs to be unused by any of the existing MTR objects. created for the current port.
[in]	params	MTR object params. Needs to be pre-allocated and valid.
[in]	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.
[out]	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_mtr_destroy()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID. Needs to be valid. created for the current port.
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_meter_disable()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID.
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_meter_enable()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID.
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_meter_profile_update()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID. Needs to be valid.
[in]	meter_profile_id	Meter profile ID for the current MTR object. Needs to be valid.
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_meter_dscp_table_update()

__rte_experimental int rte_mtr_meter_dscp_table_update	(	uint16_t	port_id,
		uint32_t	mtr_id,
		enum rte_color *	dscp_table,
		struct rte_mtr_error *	error
	)

MTR object DSCP table update

Parameters

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID. Needs to be valid.
[in]	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).
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_policer_actions_update()

__rte_experimental int rte_mtr_policer_actions_update	(	uint16_t	port_id,
		uint32_t	mtr_id,
		uint32_t	action_mask,
		enum rte_mtr_policer_action *	actions,
		struct rte_mtr_error *	error
	)

MTR object policer actions update

Parameters

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID. Needs to be valid.
[in]	action_mask	Bit mask indicating which policer actions need to be updated. One or more policer actions can be updated in a single function invocation. To update the policer action associated with color C, bit (1 << C) needs to be set in action_mask and element at position C in the actions array needs to be valid.
[in]	actions	Pre-allocated and pre-populated array of policer actions.
[out]	error	Error details. Filled in only on error, when not NULL.

Returns: 0 on success, non-zero error code otherwise.

◆ rte_mtr_stats_update()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID. Needs to be valid.
[in]	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.
[out]	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_mtr_stats_read()

__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

[in]	port_id	The port identifier of the Ethernet device.
[in]	mtr_id	MTR object ID. Needs to be valid.
[out]	stats	When non-NULL, it contains the current value for the statistics counters enabled for the current MTR object.
[out]	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.
[in]	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.
[out]	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

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ rte_mtr_stats_type

◆ rte_mtr_algorithm

◆ rte_mtr_policer_action

◆ rte_mtr_error_type

Function Documentation

◆ rte_mtr_capabilities_get()

◆ rte_mtr_meter_profile_add()

◆ rte_mtr_meter_profile_delete()

◆ rte_mtr_create()

◆ rte_mtr_destroy()

◆ rte_mtr_meter_disable()

◆ rte_mtr_meter_enable()

◆ rte_mtr_meter_profile_update()

◆ rte_mtr_meter_dscp_table_update()

◆ rte_mtr_policer_actions_update()

◆ rte_mtr_stats_update()

◆ rte_mtr_stats_read()