rte_mtr.h(3)

📦

version 25.11.3 · 9 versions

25.11.3 · ubuntu resolute, ubuntu stonking (latest)
25.11 · centos-stream 9
26.03 · nixos 26.05, nixpkgs unstable
24.11.8 · debian trixie
24.11.3 · ubuntu questing
24.11.2 · fedora 43
24.11.4 · fedora 43, fedora 44
25.11 · centos-stream 10, ubuntu resolute
24.11.4 · debian trixie

💖 rte_mtr.h — Library Functions Manual 💖

okay bestie, buckle up, we're doing the rte_mtr.h(3) page. this is the RTE Generic Traffic Metering and Policing API and it is a lot, but you're gonna eat it up, i promise. grab a boba, we're going in. 🧋✨

🌸 NAME 🌸

rte_mtr.h — the header for the RTE Generic Traffic Metering and Policing API. (manual section 3, library functions, iykyk)

🦋 SYNOPSIS 🦋

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

✨ Data Structures ✨

the lil struct squad, no cap:

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 ✨

these two, iconic:

#define rte_mtr_policy_pass_color(policy)
#define rte_mtr_policy_drop_red(policy)

✨ Enumerations ✨

here come the enums, and they said "be thorough or be nothing":

enum rte_mtr_stats_type — the counter menu:

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 — pick your metering algorithm, queen:

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 — where even is the color coming from:

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 — every flavor of "something went wrong bestie":

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 ✨

all twenty of them, glowing, experimental, and ready. every single one is __rte_experimental btw, we'll talk about that in a sec. 💅

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)
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)
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)
rte_mtr_meter_profile_get — __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_mtr_meter_policy_validate — __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_mtr_meter_policy_add — __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_mtr_meter_policy_get — __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_mtr_meter_policy_delete — __rte_experimental int rte_mtr_meter_policy_delete (uint16_t port_id, uint32_t policy_id, struct rte_mtr_error *error)
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)
rte_mtr_destroy — __rte_experimental int rte_mtr_destroy (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error *error)
rte_mtr_meter_disable — __rte_experimental int rte_mtr_meter_disable (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error *error)
rte_mtr_meter_enable — __rte_experimental int rte_mtr_meter_enable (uint16_t port_id, uint32_t mtr_id, struct rte_mtr_error *error)
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)
rte_mtr_meter_policy_update — __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_mtr_meter_dscp_table_update — __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_mtr_meter_vlan_table_update — __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_mtr_color_in_protocol_set — __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_mtr_color_in_protocol_get — __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_mtr_color_in_protocol_priority_get — __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_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)
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)

🌈 Detailed Description 🌈

RTE Generic Traffic Metering and Policing API

so like. this interface gives you the ability to configure the traffic metering and policing (MTR) in a generic way. generic as in, not tied to one specific implementation. slay.

The processing done for each input packet hitting a MTR object is:

A) Traffic metering — the packet gets 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)
color blind mode — which is equivalent to considering all input packets initially colored as green

B) Policing — there's 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. fr fr, don't get too attached, it might get a glow-up. 😭

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

(translation: everyone keeps their own color, no drama, no recolor, no drop. it's giving "we're all valid" energy. 🫶)

Definition at line 724 of file rte_mtr.h.

🎀 `#define rte_mtr_policy_drop_red( policy)` 🎀

Value:

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

(so green and yellow just vibe, and red gets the boot. red really said "not today" and got dropped. 🔥)

Definition at line 766 of file rte_mtr.h.

okay bestie we're only one third of the way through this page, don't go anywhere yet — there's more coming. 🦋✨

✨ ENUMERATION TYPE DOCUMENTATION ✨

okay bestie, this is the part where all the 💫 types 💫 live — the enums that tell you what stats you can count, which metering algorithm you're running, how input color gets detected, and what kind of error you're staring at when stuff goes sideways. let's get into it 💅

enum `rte_mtr_stats_type` 📊

Statistics counter type — it's literally which counter you're asking for. Pick your fighter 🫶

Enumerator

RTE_MTR_STATS_N_PKTS_GREEN — the number of packets the policer waved through as green ✅
RTE_MTR_STATS_N_PKTS_YELLOW — the number of packets the policer waved through as yellow 💛
RTE_MTR_STATS_N_PKTS_RED — the number of packets the policer waved through as red ❤️
RTE_MTR_STATS_N_PKTS_DROPPED — the number of packets the policer dropped 💀
RTE_MTR_STATS_N_BYTES_GREEN — the number of bytes that passed as green ✅
RTE_MTR_STATS_N_BYTES_YELLOW — the number of bytes that passed as yellow 💛
RTE_MTR_STATS_N_BYTES_RED — the number of bytes that passed as red ❤️
RTE_MTR_STATS_N_BYTES_DROPPED — the number of bytes the policer dropped 💀

Definition at line 61 of file rte_mtr.h.

enum `rte_mtr_algorithm` 🎛️

Traffic metering algorithms — the little menu of metering vibes your MTR object can run in. choose wisely, bestie 🧚

Enumerator

RTE_MTR_NONE — no traffic metering is happening at all, the output color is the same as the input color for every single input packet. the meter of the MTR object is working in pass-through mode, which has the 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 — the way your packet's input color gets figured out.

ngl this one's got lore, so read it properly: more than one of the methods can be enabled for a given meter. but even if it's enabled, a method might not be applicable to every input packet — that happens when the associated protocol header isn't present in the packet. so here's the rule, bestie: the highest priority method that is both enabled for the meter AND applicable for the current input packet wins. and if none is both enabled and applicable? the default input color is used. periodt 💅

See also: function rte_mtr_color_in_protocol_set()

Enumerator

RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN — turns on detection of the packet input color based on the outermost VLAN header fields DEI (1 bit) and PCP (3 bits). those fields get used as an index into the VLAN table. 🔎

See also: struct rte_mtr_params::vlan_table

RTE_MTR_COLOR_IN_PROTO_INNER_VLAN — turns on detection of the packet input color based on the innermost VLAN header fields DEI (1 bit) and PCP (3 bits). again, those fields are used as an index into the VLAN table. 🔎

See also: struct rte_mtr_params::vlan_table

RTE_MTR_COLOR_IN_PROTO_OUTER_IP — turns on detection of the packet input color based on the outermost IP DSCP field. those fields are used as an index into the DSCP table. 🔎

See also: struct rte_mtr_params::dscp_table

RTE_MTR_COLOR_IN_PROTO_INNER_IP — turns on detection of the packet input color based on the innermost IP DSCP field. yes, again — used as an 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 — aka the "what went wrong" dropdown.

most of them give you the type of the object referenced by struct rte_mtr_error::cause. iykyk 👀

Enumerator

RTE_MTR_ERROR_TYPE_NONE — no error. literally nothing wrong, we're so back 🎀
RTE_MTR_ERROR_TYPE_UNSPECIFIED — cause unspecified. it's giving ✨mystery✨ 😭

Definition at line 525 of file rte_mtr.h.

💅 FUNCTION DOCUMENTATION 💅

alright bestie, now for the actual functions. every single one, no skips, no cuts 🫶

`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 — go fetch what this bad boy can actually do.

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_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 brand new meter profile with its ID set to meter_profile_id. the shiny new profile then gets 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_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 — yeet an existing meter profile. ⚠️ heads up: this operation fails when there's currently at least one user (i.e. an MTR object) of this profile. so no deleting while it's still in use, bestie.

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_mtr_meter_profile_get` 🔍

__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 — grab the 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_mtr_meter_policy_validate` ✅

__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.

here's the tea 🍵 — 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. and the best part: this function has no effect on the target device. it's just a vibe check, nothing more 💅

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_mtr_meter_policy_add` ➕👑

__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, and the same policy can be used to create multiple MTR objects. so reusable, so slay 🌸

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_mtr_meter_policy_get` 🔎

__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 — grab the 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_mtr_meter_policy_delete` 🗑️✨

__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. ⚠️ and again: this operation fails when there's currently at least one user (i.e. an 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_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 runs as part of the associated flow action for traffic metering and policing. main character energy fr fr 👑

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_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. ⚠️ warning bestie: this operation fails when there's currently at least one user (i.e. a 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_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.

so here's what actually happens when you do this 🫶 in the 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. 🌈

and important: note that the policer and the statistics of the current MTR object are working as usual while the meter is disabled. also, no action is taken and this function returns successfully when the meter of the current MTR object is already disabled — so no need to stress about double-disabling 💅

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_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 — turning the meter ON, bestie ✨

Enables the meter of an existing MTR object. And okay, here's the cute part: if the MTR object already has its meter enabled, nothing happens at all — no action taken, no drama, and the function still returns successfully. It's just like, "okay girl we been knew" 💅.

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_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

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_mtr_meter_policy_update` 🦋

__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_mtr_meter_dscp_table_update` 💖

__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 — the main character table glow-up ✨

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_mtr_meter_vlan_table_update` 🌈

__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.

Bestie, yes — the source page literally says "for each value of the each value of the DEI(1bit), PCP(3 bits) input packet field". We are not fixing it. It stays exactly as the docs wrote it, iconic typo and all 💅.

Returns

0 on success, non-zero error code otherwise.

👑 `rte_mtr_color_in_protocol_set` 👑

__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.

Okay so here's the lore 🧚: more than one of the method can be enabled for a given meter. And even if it's enabled, a method might not be applicable to each input packet, in case the associated protocol header is not present in the packet. So which one wins? The highest priority method that is both enabled for the meter and also applicable for the current input packet. If none is both enabled and applicable, the default input color is used. Periodt.

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_mtr_color_in_protocol_get` 💜

__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_mtr_color_in_protocol_priority_get` 🎀

__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_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 — stats selectivity, slay 📊

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_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

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.

And that's a wrap on rte_mtr.h(3), bestie — literally the whole thing, every flag and every 0-on-success intact, no cap 🫶. This bad boy is DPDK Version 25.11.3, page rte_mtr.h(3), auto-generated by Doxygen for DPDK from the source code. Go forth and meter responsibly, queen 👑✨

📦 where this page comes from

ubuntu resolute: dpdk-doc 25.11.3-0ubuntu0.26.04.1 · BSD-3-Clause
ubuntu stonking: dpdk-doc 25.11.3-1 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

rte_mtr.h(3)

💖 rte_mtr.h — Library Functions Manual 💖

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

✨ Data Structures ✨

✨ Macros ✨

✨ Enumerations ✨

✨ Functions ✨

🌈 Detailed Description 🌈

💅 Macro Definition Documentation 💅

🎀 #define rte_mtr_policy_pass_color( policy) 🎀

🎀 #define rte_mtr_policy_drop_red( policy) 🎀

✨ ENUMERATION TYPE DOCUMENTATION ✨

enum rte_mtr_stats_type 📊

Enumerator

enum rte_mtr_algorithm 🎛️

Enumerator

enum rte_mtr_color_in_protocol 🌈

Enumerator

enum rte_mtr_error_type 🚨

Enumerator

💅 FUNCTION DOCUMENTATION 💅

rte_mtr_capabilities_get 👑

Parameters

Returns

rte_mtr_meter_profile_add ➕

Parameters

Returns

rte_mtr_meter_profile_delete 🗑️

Parameters

Returns

rte_mtr_meter_profile_get 🔍

Parameters

Returns

rte_mtr_meter_policy_validate ✅

Parameters

Returns

rte_mtr_meter_policy_add ➕👑

Parameters

Returns

rte_mtr_meter_policy_get 🔎

Parameters

Returns

rte_mtr_meter_policy_delete 🗑️✨

Parameters

Returns

rte_mtr_create 🌟

Parameters

Returns

rte_mtr_destroy 💥

Parameters

Returns

rte_mtr_meter_disable 🚫

Parameters

🫶 rte_mtr_meter_enable 🫶

🌸 rte_mtr_meter_profile_update 🌸

🦋 rte_mtr_meter_policy_update 🦋

💖 rte_mtr_meter_dscp_table_update 💖

🌈 rte_mtr_meter_vlan_table_update 🌈

👑 rte_mtr_color_in_protocol_set 👑

💜 rte_mtr_color_in_protocol_get 💜

🎀 rte_mtr_color_in_protocol_priority_get 🎀

🔥 rte_mtr_stats_update 🔥

🍓 rte_mtr_stats_read 🍓

💫 Author 💫

🎀 `#define rte_mtr_policy_pass_color( policy)` 🎀

🎀 `#define rte_mtr_policy_drop_red( policy)` 🎀

enum `rte_mtr_stats_type` 📊

enum `rte_mtr_algorithm` 🎛️

enum `rte_mtr_color_in_protocol` 🌈

enum `rte_mtr_error_type` 🚨

`rte_mtr_capabilities_get` 👑

`rte_mtr_meter_profile_add` ➕

`rte_mtr_meter_profile_delete` 🗑️

`rte_mtr_meter_profile_get` 🔍

`rte_mtr_meter_policy_validate` ✅

`rte_mtr_meter_policy_add` ➕👑

`rte_mtr_meter_policy_get` 🔎

`rte_mtr_meter_policy_delete` 🗑️✨

`rte_mtr_create` 🌟

`rte_mtr_destroy` 💥

`rte_mtr_meter_disable` 🚫

🫶 `rte_mtr_meter_enable` 🫶

🌸 `rte_mtr_meter_profile_update` 🌸

🦋 `rte_mtr_meter_policy_update` 🦋

💖 `rte_mtr_meter_dscp_table_update` 💖

🌈 `rte_mtr_meter_vlan_table_update` 🌈

👑 `rte_mtr_color_in_protocol_set` 👑

💜 `rte_mtr_color_in_protocol_get` 💜

🎀 `rte_mtr_color_in_protocol_priority_get` 🎀

🔥 `rte_mtr_stats_update` 🔥

🍓 `rte_mtr_stats_read` 🍓